Templating¶
Kiln provides a templating mechanism that provides full access to XSLT for creating the output, and an inheritance mechanism.
Template inheritance allows for a final template to be built up of a base skeleton (containing the common structure of the output) and ‘descendant’ templates that fill in the gaps.
This inheritance system works in much the same way as Django’s template inheritance.
Using a template¶
To apply a template to a content source, a Cocoon map:transform
is used,
as follows:
<map:transform src="cocoon://_internal/template/path/to/template.xsl"/>
The matching template looks for the file
assets/templates/path/to/template.xml
. Note that the extension of the
template file is xml.
Writing a template¶
The basic structure of a template is as follows:
<kiln:root xmlns:kiln="http://www.kcl.ac.uk/artshums/depts/ddh/kiln/ns/1.0"
xmlns:xi="http://www.w3.org/2001/XInclude">
<kiln:parent>
<xi:include href="base.xml"/>
</kiln:parent>
<kiln:child>
<kiln:block name="head-title">
</kiln:block>
</kiln:child>
</kiln:root>
In a base template (that is, one that does not extend another
template), there are no kiln:parent
or kiln:child
elements,
only kiln:root
and kiln:block
elements (and whatever content
the template may hold, of course).
In a template that extends another, the template being extended is
referenced by an xi:include
, the only allowed content of
kiln:parent
.
Blocks¶
Block names must be unique within a template.
Attribute blocks¶
In order to create a block to cover the contents of an attribute,
define a block immediately after the element holding the attribute,
specifying the name of the attribute it is a block for in the
attribute
attribute.
<ul>
<kiln:block name="ul-class" attribute="class">
<xsl:text>block default</xsl:text>
</kiln:block>
</ul>
Multiple attribute blocks for the same element should simply be defined in series. It is only necessary that they occur before any non-attribute blocks within that element.
Inheriting content¶
In addition to supplying its own content, a block may include the
content of the block it is inheriting from. To do so, an empty
kiln:super
element should be added wherever the inherited content
is wanted (multiple kiln:super
elements may occur within a single
block.
<kiln:block name="nav">
<kiln:super/>
<p>Extra navigation here.</p>
</kiln:block>
If the block being inherited also contains an kiln:super
element, then that
referenced content will also be included.
Dynamic content¶
Templates use XSLT as the coding language to create any dynamic content.
xsl:stylesheet
and xsl:template
elements must not be used; the process
that compiles the template into an XSLT wraps the template’s XSL statements in
a single xsl:template
element matching on “/”; all processing occurs within
this template, or imported/included XSLT.
xsl:import
and xsl:include
elements may be used (and the compiler will
move them to the beginning of the XSLT), as may xsl:apply-templates
and
xsl:call-template
.
Referencing assets¶
To reference assets (such as images, CSS and JavaScript files), ensure that the default variables XSLT is imported, and append the path to the file (relative to the assets directory) after the variable reference {$kiln:assets-path}.
<xsl:import href="cocoon://_internal/template/xsl/stylesheets/defaults.xsl" />
<kiln:block name="css">
<link href="{$kiln:assets-path}/foundation/css/normalize.css"
rel="stylesheet" type="text/css" />
</kiln:block>
This ensures that nothing that might change between installations (such as development serving the files files through Kiln, and production serving them off another dedicated server) is hard-coded into your templates.
See the settings in stylesheets/defaults.xsl
for possible
configurations.