5.3.2 Defining and Using Themes

In addition to the templates that define how each node should be rendered, there are also templates that define page layouts. Page layouts are used whenever a node in the document generates a new file. Page layouts generally include all of the markup required to make a complete document of the desired DTD, and may include things like navigation buttons, tables of contents, breadcrumb trails, etc. to link the current file to other files in the document.

When rendering files, the content of the node is generated first, then that content is wrapped in a page layout. The page layouts are defined the same way as regular templates; however, they all include “-layout” at the end of the template name. For example the sectioning commands in L^aT_eX would use the layout templates “section-layout”, “subsection-layout”, “subsubsection-layout”, etc. Again, these templates can exist in files by themselves or multiply specified in a zpts file. If no layout template exists for a particular node, the template name “default-layout” is used.

Since there can be several themes defined within a renderer, theme files are stored in a subdirectory of a renderer directory. This directory is named ‘Themes’. The ‘Themes’ directory itself only contains directories that correspond to the themes themselves where the name of the directory corresponds to the name of the theme. These theme directories generally only consist of the layout files described above, but can override other templates as well. Below is a file listing demonstrating the structure of a renderer with multiple themese.

# Renderer directory: contains template files
XHTML/

# Theme directory: contains theme directories
XHTML/Themes/

# Theme directories: contain page layout templates
XHTML/Themes/default/
XHTML/Themes/fancy/
XHTML/Themes/plain/

Note: If no theme is specified in the document configuration, a theme with the name “default” is used.

Since all template directories are created equally, you can also define themes in template directories specified by environment variables as described in section . Also, theme files are searched in the same way as regular templates, so any theme defined in a renderer superclass’ directory is valid as well.