ophelia 0.4.1

Static content

Consider Ophelia as SSI on drugs. It’s not fundamentally different, just a lot friendlier and more capable.

Use Ophelia for sites where you basically write your HTML yourself, except that you need write the recurring stuff only once. Reducing repetition to zero comes at a price: your site must follow a pattern for Ophelia to combine your templates the right way.

Consider your site’s layout to be hierarchical: there’s a common look to all your pages, sections have certain characteristics, and each page has unique content. It’s crucial to Ophelia that this hierarchy reflect in the file system organization of your documents; how templates combine is deduced from their places in the hierarchy of directories.

Dynamic content

Ophelia makes the Python language available for including dynamic content. Each template file may include a Python script. Python scripts and templates contributing to a page share a common set of variables to modify and use.

Ophelia’s content model is very simple and works best if each content object you publish is its own view: the page it is represented on. If you get content from external resources anyway (e.g. a database or a version control repository), it’s still OK to use Ophelia even with multiple views per content object as long as an object’s views don’t depend on the object’s type or even the object itself.

Trying to use Ophelia on a more complex site will lead to an ugly entanglement of logic and presentation. Don’t use Ophelia for sites that are actually web interfaces to applications, content management systems and the like.

Template files

For each request, Ophelia looks for a number of template files. It takes one file named “__init__” from each directory on the path from the site root to the page, and a final one for the page itself. The request is served by Ophelia if that final template is found.

When building the page, the page’s template is evaluated and its content stored in what is called the inner slot. Then each template on the way back from the page to the root is evaluated in turn and may include the current content of the inner slot. The result is stored in the inner slot after each step.

The result of processing the root template is served as the page.

Python scripts

Each template file may start with a Python script. In that case, the script is separated from the template by the first occurrence of an “<?xml?>” tag on a line of its own (except for whitespace left or right). If the template file contains only a Python script but not actually a template, put “<?xml?>” in its last line.

Python scripts are executed in order while traversing from the site root to the page. They are run in the same namespace of variables that is later used as the evaluation context of the templates. Variables that are set by a Python script may be used and modified by any scripts run later, as well as by TALES expressions used in the templates.

The namespace is initialized by Ophelia with a single variable, __request__, that references the request object. Thus, scripts have access to request details and traversal internals. In addition to setting variables, scripts may also import modules, define functions, access the file system, and generally do anything a Python program can do.

Documents on disk

Generally, a site will include documents that cannot be assembled from templates as described above. These are assets like images, javascript files and style sheets as well as pages that, e.g., may have been exported by some other system such as a source-code documentation generator.

In order to mix such content into the URL space of an Ophelia-generated site, the template hierarchy must omit the relevant paths and a second directory hierarchy which directly corresponds to the URL-space needs to contain the documents to be delivered from disk. If Ophelia then finds that it cannot serve a request using the templates, it will fall back to the on-disk documents. Only if the latter do not include a file corresponding to the requested URL will a “404 Not found” error response be sent.