Can you bring back the documentation on extends and includes?

[sam-hoffman]

I found some deleted documentation on extends and includes in the git history - https://github.com/pwwang/liquidpy/blob/bbe9cf672eca96e3d44715a16ae31dab377dab19/docs/extends_include.md

It was helpful! Could it be undeleted, please?

[pwwang]

That documentation was for the code before refactoring.
Now liquidpy is using extends/include from jinja2 itself. You can find documentation for them below:

https://jinja.palletsprojects.com/en/3.0.x/templates/#include
https://jinja.palletsprojects.com/en/3.0.x/templates/#template-inheritance

[sam-hoffman]

ok, thanks! would it be possible to mention in the main documentation that this is how extends and includes works now? It was a little hard to figure out

[lovering810]

Specific include Example

Adding on to this: the docs on compatibility explicitly say that with Jekyll,

passing variables to a sub-template using include tag is not supported

implying that it is supported in other modes. Is it? (I've also looked into doing what the Jekyll recommendation states, which is using Jinja2's with statement, but sadly, that is now deprecated, which is probably a docs update of its own.)

The following throws a TemplateSyntaxError: expected token 'end of statement block', got 'code'

"system":{% include 'ValueSet/SystemReference' code: Identifier.root %}

What is the expected behavior? Should include in wild mode correctly retrieve the template and apply the locally-set variable? Is there another way to do this that I'm missing? I've spent some time in the Shopify, Jinja, and liquidpy docs, but am not sure which governs this behavior, as they are all in kind of different places about it (Shopify deprecated include, Jinja2 deprecated with - "Changed in version 2.9: This extension is now built-in and no longer does anything.", and liquidpy docs don't talk about this functionality in particular).

[pwwang]

Thanks for pointing this out.

Passing variables via include is not supported in any mode. I was mentioning this in the doc is because, amongst those variants of liquid, jekyll is the only one that supports the include tag.

However, you are correct that with is deprecated by jinja, by default, the sub-template by include has access to the variables where it's included. So the default behavior is:

{% include 'ValueSet/SystemReference' with context %}

See https://jinja.palletsprojects.com/en/3.0.x/templates/#include

If you want code to be accessed inside your template ValueSet/SystemReference:

{% assign code = Identifier.root %}
{% include 'ValueSet/SystemReference' %}

But the best practice is that, if you want flexibility in your sub-template, you should use macros combined with import.

See this answer: https://stackoverflow.com/a/9405157/5088165

See also tests that I added regarding this issue:
https://github.com/pwwang/liquidpy/blob/dev/tests/wild/test_include.py