search

Keats / tera

A template engine for Rust based on Jinja2/Django
http://keats.github.io/tera/
MIT License
3.43k stars 279 forks source link

What is a `block`? #840

Open SMUsamaShah opened 1 year ago

SMUsamaShah commented 1 year ago

Looking at the docs, the very first thing it uses is block and endblock but it is never explained anywhere in the doc what it is and how it works and should be used.

I think it assumes previous knowledge of Jinja or other template engines this concept is taken from.

Please explain block in the docs too. Thanks

Keats commented 1 year ago

Have you seen https://tera.netlify.app/docs/#inheritance ?

SMUsamaShah commented 1 year ago

Yes.

Tera uses the same kind of inheritance as Jinja2 and Django templates: you define a base template and extend it in child templates through blocks

A base template typically contains the basic document structure as well as several blocks that can have content.

This base.html template defines 4 block tags that child templates can override. The head and footer block have some content already which will be rendered if they are not overridden.

It never once says what is a block and how am I supposed to use it.

The very first line of code example in README.md on github is

<title>{% block title %}{% endblock title %}</title>

It left me confused. What does title within the braces mean here? There is nothing between these two blocks here, should there be something like

<title>{% block title %}Title of my site{% endblock title %}</title>

or should there be a variable here? because in next lines of that code this block title is never seen used.

BTW, now after writing all of the above I think block defines a template which can be used elsewhere in using the name of the block, not sure. I still stand by my initial complain anyway.

jonathan-s commented 1 year ago

It does say.

This base.html template defines 4 block tags that child templates can override. The head and footer block have some content already which will be rendered if they are not overridden.

And then goes on with how the child template looks. Is there anything that is unclear there?

In short; the child template inherits / extends from base.html. When the child template uses block it will fill in content from the child rather than use the block defined in the parent.