evoque

The $begin{label} and the $end{label} pair of directives define a nested template, addressable from any other template. A nested template has all the characteristics of top-level file or string templates -- the only difference is in how they are addressed. In fact, for the case of top-level file or string templates, you may consider that the begin and end directives are simply just implied by the beginning and end of the string. The label may be considered just as a named anchor, a destination inside the file to which one can point to directly.

Parameters

There is really only one parameter, and that is the label that is what is used to address the template.

Rules

• A label defining a nested template (whatever the nesting level) may be used once and only once in a template file or string.
• Nested templates must be addressed via their label, using a syntax similar to fragment identifiers of a URL, i.e. #label. When being addressed locally, i.e. from same file or string, nested templates may be addressed with just #label. From within other templates, the information to identify the top-level template must also be specified, e.g. template_name#label for an explicitly named template, or by something like template.html#label for a template implicitly named by its file name.
• For overlay templates it is possible to explicitly specify what level the lookup for a locally addressed nested template should start from i.e. if the name starts with a single "#" then from current current, if with "##" then from one level down, if with "###" then from two levels down, etc.
• Nesting of templates may be multi-level; addressing is always flat, i.e. a nested template may further nest other templates, but all templates irrespective of nesting depth are addressed either (locally) with #label or with template_name#label.
• If only one of the begin or end directives is present, then the other is implied by, respectively, the beginning or the end of the string.
• A nested template is not automatically rendered when the template that defines it is rendered; it must be explicitly evoque'd.
• Everything already established about directives applies, e.g. both begin and end may all be on same line, or each may span many lines; any of the two allowed delimeter pairs may be used; any whitespace around the label is ignored, etc.

Execution

Nested templates are the def, the macro, the callable block, the sub-template of Evoque. To be executed, they are evoque'd:

This will evaluate the nested template using a copy of the caller's context. Note that given that a nested template is a template in its own right, it can specify its own default data (and other preferences) that is what will be used when the caller's context does not specify a required variable. If neither caller nor default data specify a required variable, an evaluation error will occur and will be reported as per the domain's errors setting.