Sub-templates in markdown

This amounts to just specifying the markdown filter on the output of
the evoque’d template. It is easy to see how it works with an example
(coming straight from the unit test data included in the
Evoque distribution).

The template

markdown.html

$begin{my-markdown-template}
### From a markdown template!

- item one 
- item two ${param}
$end{my-markdown-template}
\
<div class="markdown-output">
$evoque{#my-markdown-template, filters=[markdown], param="<xml/>"}\
</div>

For simplicity, we just use a single file, where the top-level template
evoques a locally-nested markdown template, but of course the source of the
sub-template could be anything you like.
Notice that all the outer template does is evoque the inner template
into a <div/>, specifying the filters to use as well as some
default data.

Output

We must supply the filter we would like to use, so we need to set it on the globals
of the evaluation namespace.
We can then render the template:

from markdown import markdown
domain.set_on_globals("markdown", markdown)
print domain.get_template("markdown.html").evoque()

That will produce the following output:

[KeyError: ‘auto’: File “/home/admin/py-packages/evoque/domain.py”, line 108, in get_collection
return self.collections[name]
: EvalError(evoque(name=u’markdown.txt’, collection=”auto”, raw=True, filters=[evoque_html_highlight]))]

Notice that automatic quoting of incoming data just happens
also for sub-templates in markdown — or in any other format.

Alternative – declaring preferred filters within template itself

A template may declare itself what filters should be used.
Sometimes we may not have write access to a template source, but in
those cases it would be easy to just read that source and wrap it into
a another template under our control. The template below
issues a $prefer{} directive with
filters=[markdown] as well as some default data,
and gives identical results as above, but relieves the caller
from the need of specifying the filters or any default data on each call.

$begin{my-markdown-template}
$prefer{ filters=[markdown], data=dict(param="<xml/>") }
### From a markdown template!

- item one 
- item two ${param}
$end{my-markdown-template}
\
<div class="markdown-output">
$evoque{#my-markdown-template}\
</div>

Using only python callables

Just to get a little closer to what is going on underneath…
declaring filters on the $evoque{} call
or the $prefer{} directive of a template is really just
a little syntactic sugar over doing everything
with pure python callables. Here’s what such an alternate version would
look like (here we are required to use the callable version of
the evoque directive):

$begin{my-markdown-template}
### From a markdown template!

- item one 
- item two ${param}
$end{my-markdown-template}
\
<div class="markdown-output">
${xml(markdown(evoque("#my-markdown-template", param="<xml/>")))}\
</div>

This will produce the exact same output when rendered as above.