Templates
=========
h2: What are templates? =#what
Templates are a flexible mechanism ewok provides to allow presentation information -
the "look and feel" of a site - to be managed separately from the authored content.
Cascading stylesheets (CSS) already provide this to some extent, but ewok takes the
principle further by allowing recurring content elements, like headers, footers,
and sidebars, to be abstracted as well. They also remove a key limitation of
stylesheets - that content authors remember to link to the appropriate stylesheet
in their pages.
ewok templates therefore provide three main benefits: they remove the
requirement that authors cooperate with site policies (such as using particular
stylesheets) or use an appropriate prefabricated static site template; they allow
for a clean separation of responsibility between authors who maintain content
and site designers who maintain the look-and-feel; and they isolate presentation
changes within the template, allowing modifications to be applied instantly
site-wide rather than piecemeal file-by-file.
h2: How do templates work? =#how
ewok templates work by providing a framework within which ewok dynamically
renders content pages. The provided content is "wrapped" with template
components, allowing standard stylesheets and recurring content elements to be
automatically added to every page.
Templates consist of three standard components that are applied to the HTML
content page as follows:
- *style component* - the style component is inserted at the beginning of
section of the HTML content. This allows standard site stylesheets to
be included, but document-specific stylesheets to override the site settings
if required. The style component can also be used for any other
section content - standard tags or customising content are
obvious examples. The default style component is named 'style.epl'.
- *header component* - the header component is inserted at the beginning of
the section of the HTML content, allowing elements like headers and
sidebars to be applied to page content. If HTML tables are used for layout,
these can be opened in the header component and closed in the footer. The
default header component is named 'header.epl'.
- *footer component* - the footer component is inserted at the end of the
section of the HTML content, allowing footer content to be added
to the page, or layout tables to be closed off. The default footer
component is named 'footer.epl'.
Components can simply contain static HTML to be inserted as-is into the
rendered page, or they can contain embperl (Embedded Perl) statements, allowing
dynamic component content (thus the '.epl' suffix). [ See the "Embperl
Overview":../user/embperl.html in the User Guide for an introduction to
embedded perl ].
Note that the ewok file manager restricts listing, creating, and editing of
template components to users with 'template' or 'admin' privilege.
h2: Template inheritance =#inheritance
Template components are inherited in an object-oriented fashion (using
EmbperlObject). ewok searches for each component beginning from the directory
containing the current content page up to the top of the current ewok tree,
as well as any supplementary directories that have been nominated for that
tree (see "ewok.conf":config.html#core for configuration details).
This allows a template to be defined for a whole website, but for individual
components to be overridden for subtrees simply by creating a lower-level
component in the subtree. For example, to override the sitewide footer within a
particular directory you just create a footer.epl there with the local footer
content, and ewok uses that instead. Empty components are also valid, so you
can turn off footers for an area simply be creating an empty footer.epl.
The recommended approach is to create a 'templates' directory at the top of
each site tree and locate the sitewide template components there, overriding
further down the tree if required. (Template components can also be placed
directory in the root directory of the tree, but if you use multiple templates
- see next section - this can server to unduly clutter your root directory)
[ For advanced EmbperlObject users it's worth pointing out that standard
Execute inheritance also works for components - you can say
"Execute '../footer.epl'" within a lower footer.epl to add to
the existing footer, for example. Even more powerfully, of course, you can also
do explicit component munging by Executing a parent component into a scalar
and then manipulating that output. ]
h2: Named templates =#named
Templates can also be named, allowing multiple templates to be defined for
an area, not just the single default template. Named template components
are again identified using using simple naming conventions, having the form
'style-.epl', 'header-.epl', and footer-.epl. Thus to
create a new 'foo' template it is only necessary to create 'style-foo.epl',
'header-foo.epl', and 'footer-foo.epl'.
In fact, it's only necessary to create any one of these components to create a
named template - if ewok does not find a named component it will fall back to
using the default one instead. This allows you to derive a named template from
the default one simply be overriding a single component.
Named templates can be selected for use (instead of the default template) in
three ways (highest precendence first):
N. Using an explicit template URL argument: adding a t= URL argument to
an ewok page will use the given template e.g. templates.html?t=foo
N. Setting an explicit template in the 'template' item in your ewok user
preferences will use that template (for you only) for all ewok pages -
useful for testing. (This can also be achieved by using an explicit
template URL argument, as above, but using a doubled tt= to force
the template to be sticky.)
N. Setting the template metadata item on a directory will use the named
template for all pages below that point in the tree. This is how to
effect more permanent template selection for a tree.
Dynamic template selection only works on staging pages, of course - published
pages are static and have had the template 'fixed'. When publishing, ewok uses
the given named template if one is defined in the directory metadata for the
published page, and the default template otherwise. ewok admins can explicitly
override the template to use when publishing.