5.4.3 simplates

5.4.3 `simplates`

Aspen comes bundled with a handler called simplates. In basic terms, a simplate is a single-file web template with an initial pure-Python section that populates the context for the template. Simplates are a way to keep logic and presentation as close together as possible without actually mixing them.

In more detail, a simplate is a template with two optional Python components at the head of the file, delimited by ASCII form feeds (this character is also called a page break, FF, <ctrl>-L, 0xc, 12). If there are two initial Python sections, then the first is exec'd when the simplate is first loaded, and the namespace it populates is saved for all subsequent invocations of this simplate. This is the place to do imports and set constants; it is referred to as the simplate's import section (be sure the objects defined here are thread-safe). The second Python section, or the first if there is only one, is exec'd within the simplate namespace each time the simplate is invoked; it is called the run-time Python section. The third section is parsed according to one of the various web templating languages. The namespace for the template section is a copy of the import section's namespace, further modified by the run-time Python section. If a simplate has no Python sections at all, then the template section is rendered with an empty context. SyntaxError is raised when parsing a simplate that has more than two form feeds.

In debugging and development modes, simplates are loaded for each invocation of the resource. In staging and production modes, simplates are loaded and cached until the filesystem modification time of the underlying file changes. If parsing the file into a simplate raises an Exception, then that is cached as well, and will be raised on further calls until the entry expires as usual.

Simplates obey an encoding key in a [simplates] section of aspen.conf: this is the character encoding used when reading simplates off the filesystem, and it defaults to 'UTF-8'.

For all simplates, the full filesystem path of the simplate is placed in its namespace as __file__ before the import section is executed.

NB: Simplates are never used in the abstract. Rather, one always uses a particular flavor of simplate that obeys the above general rules but which provides slightly different semantics corresponding to the web framework upon which each flavor is based.

The Aspen distribution currently bundles two flavors of simplate: Django-flavored and stdlib-flavored. The WSGI callables for each are defined in the aspen.handlers.simplates module:

django( environ, start_response): Serve environ['PATH_TRANSLATED'] as a Django-flavored simplate.

stdlib( environ, start_response): Serve environ['PATH_TRANSLATED'] as a stdlib-flavored simplate.

5.4.3.1 Django-flavored

In addition to the aspen.apps.django_ app, which serves Django in usual monolithic fashion, we also provide a handler that integrates the Django web framework with the simplate pattern. As mentioned, this callable is available as django in the aspen.handlers.simplates module.

5.4.3.1.1 Installation

To use Django simplates, first install the Django framework in your site:

Put django on your PYTHONPATH (e.g., in __/lib/python).
Put your Django project on your PYTHONPATH (e.g., in __/lib/python).
Add a [django] section to aspen.conf, with a settings_module key that points to your settings module.
Configure any database settings, etc., in your Django project's settings module.

Then tell Aspen to use the django simplate handler for various files via the __/etc/handlers.conf file. For example, the following handlers.conf would serve files ending in .html as Django simplates, and would serve all other resources statically:

fnmatch     aspen.rules:fnmatch
catch_all   aspen.rules:catch_all

[aspen.handlers.simplates:django]
fnmatch *.html

[aspen.handlers.static:wsgi]
catch_all

Lastly, close the loop by telling Django about simplates via the urls.py file in your Django project package, like so:

from django.conf.urls.defaults import *

urlpatterns = patterns('',
     (r'^', include('aspen.handlers.simplates.django_'))
)

Admittedly, that is a fair amount of wiring. The main benefits to using Django via Aspen simplates are first, that your view code and template code are together in the same file (without being mixed); and second, that you get filesystem- rather than regex-based URL layouts.

5.4.3.1.2 Distinctives

Django-flavored simplates have these distinctives:

The simplate namespace is a Django RequestContext.
The template section is compiled as a Django template.
If the run-time Python section raises SystemExit with a Django HttpResponse object as its argument, and no other response object is defined in the section, then the SystemExit response is sent back and the templating section is skipped entirely.
If the run-time Python section raises SystemExit without a Django HttpResponse object as its argument, and no other response object is defined in the section, then processing of the run-time section ends and processing proceeds to rendering the template.
If the run-time Python section defines a response object, then (whether or not the run-time section is terminated with SystemExit) this object is assumed to be a Django HttpResponse object, and the template is rendered to it.

5.4.3.2 Standard Library-flavored

Aspen includes a simplate flavor that has no dependencies outside the standard library, effectively giving you a raw WSGI interface. The handler for this is named stdlib and is defined in the aspen.handlers.simplates module. Here are its distinctives:

The run-time Python section has two additional names in its namespace, environ and start_response, corresponding to the parameters of the handler as specified above.
If the run-time Python section raises SystemExit, this is silently ignored.
If the run-time Python section defines a response object, this is assumed to be an iterable per the WSGI specification and is returned as such. The template section is skipped.
The template section is rendered using mapping-based string interpolation.