evoque

Any Evoque template, be it file-based or string-based, top-level or nested, is addressable from any other Evoque template in the domain. From within a template, $evoque{name, **kw} is the directive that gets and renders a template -- it combines the full functionality of the two methods you would need to call to do the same thing from within an application, i.e. the methods Collection.get_template() and Template.evoque().

Parameters

Rules

The only required parameter is name, that must always be specified first, and most often the call is as simple as: $evoque{name}.

Note that for convenience the name parameter may be specified as an unquoted string literal i.e. when the name= qualifier is not explicitly stated, the string found will be interpreted as a literal even if it is not enclosed in quotes. For example, for a template with name my_template, using any of the following 3 forms is perfectly equivalent: $evoque{my_template}, $evoque{"my_template"}, $evoque{name="my_template"}. But, $evoque{name=my_template} will cause the runtime evaluation of a my_template variable that will be used as the name.

The evoque directive gets the named template from the specified collection -- if collection=None, then the calling template's own collection is used, otherwise collection must name an already existing collection. Template may still need to be loaded. If it is already loaded, the template is retrieved from the cache, subject to cache staleness checking as per the collections's cache settings.

The src, input_encoding parameters are only used in the event that the template needs to be loaded:

• if template is not yet loaded then it is assumed to be a file-based template and the location of the file to load is given by joining the collection's base path and the value of src.
• if src=None then name is interpreted as the location of file to load.

All parameters other than name, src, collection, if not specified, will be set to the collection's default.

The raw parameter determines whether the raw template string is to be returned, without any evaluation, e.g. for the purpose of editing the template string itself. Note that if the template is not yet loaded and raw=True, then it will be loaded but not compiled. See the raw source howto for more details.

The quoting parameter determines what the default quoting class for the template is (if the template is not yet loaded) and/or which quoting class to use for this evoque'ation.

Any specified filters, that must be either None or a sequence of filter functions, are executed after evaluation. Filters must of course be available in the evaluation space.

An evoque'd sub-template will be quoted as per the quoting class of the calling template. This of course will only happen in the event that the two templates use different quoting classes.

Built-in callable

The $evoque{name, **kw} directive is also provided as the perfectly equivalent built-in callable:

• "name" is now a normal python string so may be evaluated, i.e. if literal, then it must be quoted.
• may be intermingled with other callables, python builtins, custom filters, etc. For example: ${markdown(evoque("my_mardown_template"))}