Templates are always part of a Collection in a Domain —
a Domain and a default Collection instance are always created,
be it explicitly or implicitly.
The preferred way to load/retrieve a Template is via a Domain instance;
the following code implicitly creates the default Collection instance:
domain = Domain("/home/user/templates") t = domain.get_template("snap.html") print t.evoque(vars())
It may sometimes be more convenient to instantiate directly;
the following code implicitly creates the Domain and the default
Collection instances:
t = Template("/home/user/templates", "snap.html") print t.evoque(vars())
Note however that implicitly creating the Domain and the default
Collection in this way will not allow you to change the default
settings for the
restricted,
errors,
log,
cache_size,
auto_reload,
slurpy_directives
Domain and Collection attributes.
Evoque is conceived with safety and security in mind.
Under no circumstances, for example, is it ever possible to evoque a
template from a file that is not within a declared collection.
Given that there is no special distinction between templates
and content, template collection root directories are treated
in the same way that a web server treats its document-root.
The template’s collection and domain
Given a template instance, you can always get the associated
collection and domain with:
template.collection template.collection.domain
To create the (default) collection first, thus having an opportunity to
name it explicitly, you do:
from evoque.collection import Collection collection = Collection(None, "default_collection", "/home/user/templates") domain = collection.domain assert collection is domain.get_collection("default_collection") assert collection is domain.get_collection()
Additional useful design principles
- Templates are organized in Collections that belong to a Domain.
- Collections have a root folder — all text files below are template-addressable.
- All collections are explicitly named — decouples template addressing from
deployment paths and protects sensitive path info within templates. - The creation of the Domain also creates the default Collection, that is named
“” (the empty string). The default collection may be given
another name, by simply creating it first. - Every template instance is associated to one and only one collection.
- All templates are assigned a nick name, unique within the
collection: memory-based templates are always named explicitly;
for file-based templates the default name is their
collection-root-relative or c-rel locator. - The src or location of any collection-qualified template
is always specified as c-rel. - A previously loaded template may be retrieved by its name and the
collection. - The eval globals dict belongs to Evoque and/or
the Client Application, and is shared by all templates
in a domain — it is not affected by template
evaluations i.e. it never changes as a side-effect
of a template being rendered. - The eval locals dict belongs to the document
being rendered, and is passed down the nested execution scope,
possibly cloned and modified each time.