Why yet another templating system?
For precisely the same reason as every other one, and a lot more!
You may wish to take a look at Evoque’s
list of distinguishing features.
Why the evoque name?
It is a triple trip tributing all at once
(a) the great little eval
python built-in,
(b) the (optional) Qpy third-party package that
not only guarantees that all data input is
always quoted but also that it is quoted once and only once,
and
(c) the act of evoking a document from a template and
a bunch of data.
Maybe these are more allusions than tributes,
possibly making all this seem a little cubist.
Don’t call me pablo,
just that, everything is related.
The three are but one.
Within a qpy.xml quoted template, how do I output escaped html?
By just declaring it unquoted, i.e. cast it to unicode.
E.g. if you want to output “<tag/>”
as part of the content in an html document, you can do
${unicode("<tag/>")}. Of course instead of
the literal “<tag/>” string you can unicode()
anything you like, even the evoque’ations of any other template.
Do I have to install Qpy?
No, but if you don’t you will need to work harder to take advantage
of the killer feature of
automatic cross-site scripting protection
— by providing your own
custom quoted-no-more class.
Or, if all you want is just to take care of input quoting manually,
see the how to do manual quoting without qpy.
Why can’t I just do $variable instead of having to always specify ${variable}?
Evoque plays defensively. Anything immediately after the $ and before the
opening { is reserved for the name of directives, with ${ taken to imply
the start of an expression. This way, other directives could be added in
the future free of any backwards compatibility issues.
Is there something like a def directive?
Yes. For evoque a def is just a sub-template, defined
with a begin/end block.
Further nesting of sub-templates, i.e. sub of a sub etc, is
also supported. A sub-template defined anywhere may be addressed
from anywhere else.
How come there is no include directive?
There is, it is called evoque.
You can evoque any text file you like, or any other template or sub-template.
By default evoque’d files are evaluated as if they were templates — to
just include raw source evoque with raw=True
(see the raw source howto).
How come there is no rawtext directive?
There is, it is called evoque, with parameter raw=True,
and if you want a different quoting you can also specify it e.g.
quoting="str".
You can evoque any template or sub-template,
e.g. any begin/end block,
or any textual file.
See the raw source howto.
Why isn’t the prefer directive just part of
the begin directive?
Because a template need not have a
begin or an end
declared, but may still wish to define some
prefer parameters —
top-level templates are implicitly delineated
by the beginning and ending of a string
(typically the text content of a file) while
nested templates (that are first-class templates in their own right)
must be delineated with begin and/or end.
What about template inheritance?
Sure, Evoque supports template inheritance like no other,
with support even for
data-driven template inheritance.
See the overlay directive.
Is it possible to import anything from within a template?
Allowing arbitrary python imports from directly within a template
will introduce a lot of difficult issues with restricted execution
mode. To support restricted mode,
a python application must retain some control on what may be added
to the evaluation context and it seems that the simplest way to
achieve this is to only allow the main application itself to affect
such additions, using the provided methods,
e.g. domain.set_namespace_on_globals().
See managing the namespace.
Why isn’t there an XML-compliant syntax?
Because Evoque is a generic text templating system, not an XML-based one.
However, there is conceptually no problem with providing an XML-compliant
syntax, e.g using processing instructions, for directives — this will
of course require a modified template parser.
Expressions, being already XML-compliant, will require no change.
I do not understand the attribute descriptions I see on this site,
for example
filters:[callable] or file:either(None, str)?
Those descriptions mimic the syntax that the
qp.lib.spec module uses to actually
specify attribute allowed values and to perform the
corresponding runtime validation checks.
Here the clarity of the syntax is only used for documentation purposes.
The examples here mean that filters is allowed to be a
list of callables (taking some liberty here, as callable
is not really a python type), and file may be
either None or an instance of str.
If you would like to know more, here’s a
little write-up on the wonderful spec module.
Or see the
spec.py source directly.
How do I specify the encoding of the output?
You don’t. It is always unicode.
Once you get the output, you can encode it as you please.
Can Evoque do all that other template systems are able to do?
Most probably, yes. It would help to know the specific task, in which case
I’ll be more than happy to help identify how it could be done with Evoque.