Template inheritance docs – thanks and notes

dakur

I'm not pretty sure where to raise the issue so I'll post it here. I've just read the new template inheritance docs and I want to express big thanks to @DavidGrudl as that is just what I was waiting for so long – now I pretty much understand all these include stuff and what they are for. Though, I have few things I want to mention, hopefully to improve it a bit further. These are my notes from reading the docs.

First, I was pretty much confused by {include block $name} syntax. I somewhat remembered what it means from a topic on this forum, but in docs it appears out of nowhere in one place and is presented together with another feature (block name passed by variable) so I was confused what the code example is related to, how does it relate to what is before and how the block thing it is different from simply {include xyz}. It was also presented as a must, I've made a PR fix so that it is presented as an option.

A small improvement would be to write a use-case for Dynamic Block Names as there is just mentioned it is there, but have no clue what that could be good for (and I would like to!).

As per horizontal inheritance, I'm not pretty sure what does the inheritance word (whether in Czech or English) mean in here. I am probably just not able to see some concept the word came from, because importing blocks from different template does not seem like class inheritance to me – maybe rather like trait. I think talking about reusability fits more here. The word reuse is used there alongside inheritance in there – what is the relationship between them actually?

Finally, when I saw embed explained there finally, a question raised in my head – why do we need {layout}, {include} and {import} any more? Couldn't we just unite it into {embed} and have 3 tags less, which would make things much clearer? Honestly, I work with Latte for years and until now I had no clear idea of the differencies between all these tags. Thus my joy of this docs article, but still, I can not say, if {include file.latte} and {import file.latte} make the same thing. Do they?

Anyway thank you once more for your work and hopefully this can help a bit.
I did not make another PR because these things need more skilled man to process. :-)

P.S.: looking forward to the day when I will be able to work with Latte API for creating macros and understand Forms API to create fully featured custom controls. These are my two favourite bits which I miss so much in the docs. :-)

Last edited by dakur (2020-12-01 13:51)

David Grudl

ad horizontal inheritance: The term horizontal reuse will maybe be better. In common with inheritance it has overriding. So when you import some blocks using {import} to the main template, you can have the same named blocks in that main template, which will overwrite them. And you can use {include parent} in that blocks to include original imported blocks.

embed vs layout vs include: {embed} can be used instead of {include} and {layout}, but it is pair macro a and you probably won't want to write {embed file.latte}{/embed} instead of {include file.latte} and wrap the whole child template in {embed 'layout.latte'} ... {/embed} instead of single {layout layout.latte} in the header.

import vs include: include is like include 'header.phtml' in PHP, import is like import from module in JavaScript, the first prints the contents, the second loads the blocks, it is not interchangeable.

dakur

import vs include: include is like include ‘header.phtml’ in PHP, import is like import from module in JavaScript, one prints the contents, the second loads the blocks, it is not interchangeable.

Aha, that was not clear. Thanks.

David Grudl

I tried to rename some terms and headings https://github.com/…8ac7a17e1804

David Grudl

I added example for Dynamic Block Names.

@dakur Are there still some unclear things?

dakur

I tried to rename some terms and headings https://github.com/…8ac7a17e1804

Yes, I think it is better, even though I've read the changes only in commit diff, not in context of whole docs chapter. Horizontal reuse still does not sound well to me as I imagine nothing under the term, but I don't know of any other better now..

I added example for Dynamic Block Names.

It's probably OK for people who desperately need such feature and are looking for it in the docs. But for those who scan docs for features or just randomly read it like me, some real world example would be better. I'm still confused what is it for as I can omit {block} and the result is still the same, isn't it? So maybe an example which points out the difference between it.

{foreach [Peter, John, Mary] as $name}
	Hi, I am {$name}.
{/foreach}

Last edited by dakur (2020-12-07 13:01)

David Grudl

Result of your example is (of course):

Hi, I am Peter.
Hi, I am John.
Hi, I am Mary.

Result of dynamic block example is:

Hi, I am Peter.
Hello. I am John.
Hi, I am Mary.

How can you not see the difference? :)

dakur

❗ I was so focused on the dynamic part that I've missed the greeting. :-D Anyway, still have no idea, what is it good for. But maybe that's not the point of docs but rather a tutorial. Thanks for pointing me. :-)

David Grudl

We'll get to that. I will try to modify the example to make it clear that we are talking about two files.

parent.latte

{foreach [Peter, John, Mary] as $name}
	{block $name}Hi, I am {$name}.{/block}
{/foreach}

child.latte

{block John}Hello. I am {$name}.{/block}

Can you think of another way to achieve the same result?

dakur

Yeah, I understood it from the previous post that there are two files. And no, I don't know how to achieve it in another way. Just trying to say that I don't know why I would even need to do it at all. From this example in docs I know Latte has such feature but I don't know what I could use the feature for – what other people use it for, why it has been even implemented. Mention about its purpose would help me to know when to use it and understand Latte deeply in its intentions.

If we do not understand each other yet we will probably have to switch to Czech as it is pretty difficult to have such discussion in English when every word meaning matters. :-D

Last edited by dakur (2020-12-08 08:26)

David Grudl

I understand. But I'm probably not able to give a real world example in that documentation chapter.

dakur

Ok. And just out of curiosity – do you remember why you've implemented it? Was it a request from someone or you had some use-case for it?

David Grudl

I added it ten years ago because it's a great solution for some use cases, like form rendering etc.

{block $input->name} {input $input} {/block}

child.latte:

{block description} ... {/block}

(And no, this is absolutely not good example for Latte-only docs)

dakur

Thanks. :-)