evoque: rendering a template

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

$evoque{ name, src, collection, raw,
quoting, input_encoding, filters, **kw }

name: required, the name of the template to evoque()

src, collection, raw, quoting, input_encoding, filters
: behave as in Domain.get_template()

**kw : any additional keyword args are set on evaluator’s locals

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
quoted-no-more 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.

Built-in callable

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

${evoque(“name”, **kw}
  • “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"))}