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.