A pass-through variable

[paleo]

Hi and thank you for this amazing template engine.

I created asynchronous tags that load data. I would need to connect calls to these tags, to the renderFile that initiates the rendering. This way, I can implement a cache system that is aware of the dependencies of generated HTML (so the cache system knows when to invalidate generated HTML).

What I did

I was able to achieve it, this way:

1. Adding a hidden property to the initial scope:

engine.renderFile(templateName, {
  ...scope,
  [RenderTag.passThroughSymbol]: ++renderingIdSeq,
});

2. Retrieve the hidden property from my tag:

  * render(ctx) {
    const renderingId = ctx.environments 
      ? ctx.environments[RenderTag.passThroughSymbol] 
      : undefined;

3. Register a modified version of RenderTag:

I used the code from the repository, with a modification:

export default class RenderTag extends Tag {
  static passThroughSymbol = Symbol("passThrough");
  
  // ...

  * render (ctx: Context, emitter: Emitter): Generator<unknown, void, unknown> {
    // ...
    const env = { [RenderTag.passThroughSymbol]: ((ctx.environments as any) ?? {})[RenderTag.passThroughSymbol] };
    const childCtx = new Context(env, ctx.opts, { sync: ctx.sync, globals: ctx.globals, strictVariables: ctx.strictVariables })

The hidden property is passed through child contexts, using a env variable.

Questions

I would like to know if the way I found is correct and perennial, or if this is more like a hack, and then, there is a risk that it won't work some day after an upgrade.

Also, a better way would be something provided by the template engine. I imagine something like that:

engine.renderFile(templateName, scope, {
    passThroughScope: (anyObjectHere),
});

…then, from the implementation of the tag, we could simply use it from a property ctx.passThroughScope.

[harttle]

There's an include tag which passes all parent scopes into sub templates. I think this can be simpler for your case. Of course the downside is you cannot control what variables are available for these sub templates.

Passing a whitelist of variables but not all (globals) is not a typical scenario though. To my understanding, it's more about tracing. I noticed there's a currentFile argument for liquid.parseFile, I guess we can somehow make a stack of filepaths into Token or Template so it will be available for all tags, then you can read this stack during parsing or rendering.

Does this approach help? What's your thoughts on this?

[paleo]

Thanks. I am happy with render and I don't want to change the behavior in my LiquidJS templates. The include tag is disabled in my project and I think it is for the better.

What I need is to pass identifiers from the call to renderFile to my custom tags.

For example, I provide custom asynchronous tags that load data from the database. Currently I can't connect the execution of my tags to a call to renderFile. So, for example, if I want to know which call to a template (including the sub-templates) is responsible for which SQL queries, I can't. And I need that for my caching system.

I looked at the function parseFile in the src/parser/parser.ts file. It seems to me that it isn't the correct place to implement it. The pass-through identifiers have to be stored in the context.

I already implemented this tracking system in a custom version of the render tag (as described upstairs): the modification is really 3 lines of code. And it works. Do you think that I can live with it? Or is it a hack that's likely to stop working one day because it goes against the way the engine works?

[jg-rp]

Using symbols to add "private" variables to a render context and reading those private variables from custom tags - as you have done - seems like a perfectly valid approach to me. As does manipulating the render context prior to rendering a partial template from a custom version of the {% render %} tag.

If you haven't already, consider implementing your async data loading and caching in a drop, possibly instead of custom tags, depending on what else those tags might be doing.

[paleo]

Then I discover the drop feature. It's interesting really! It would be more useful if we could pass parameters but I will think about it. Maybe I can redesign and replace some of my tags. Thanks a lot!

Using symbols to add "private" variables to a render context and reading those private variables from custom tags - as you have done - seems like a perfectly valid approach to me.

It is reassuring. :-)

[jg-rp]

👍 In general, when deciding what objects and tags to expose to template authors, if a thing is a resource, I prefer an object (possibly a lazy loading drop), along with filters that expect to work on that object if template authors need to provide arguments to work with it.

{{ someResource | do_a_thing: argument  }}

If the thing is an action, it's probably better implemented as a tag.

{% dothing argument=value %}
{% render 'argument' %}