Usage from within a Python application

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.