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.