Deliverance is a program that applies themes to content according to a set of rules.

Glossary

Rules

These describe the way the theme is applied to the content.

Theme

This contains the style information to be applied to the content. Typically it is an HTML page that is a model for all the pages on a site.

Content

This is the page originally requested by the browser.

Deliverance

This is the program that applies the theme to the content according to the rules.

The Rules

The rules are provided in an XML file that looks like:

<?xml version="1.0" encoding="UTF-8"?>
<rules xmlns="http://www.plone.org/deliverance">
<replace theme="(xpath)" content="(xpath)" />
<copy theme="(xpath)" content="(xpath)" />
<append theme="(xpath)" content="(xpath)" />
</rules>

All elements and attributes are in the namespace "http://www.plone.org/deliverance".

The rules all follow a common form. The tag ("replace", "copy", "append", or "append-or-replace") gives a command. An XPath expression is used to determine the element in the theme (the "theme" attribute), and another XPath expression to determine the element in the content (the "content" attribute).

Any rule may optionally contain an attribute onerror which controls the delivery of error messages. If onerror="ignore", rules which result in errors are skipped without reporting the error.

Generally, when the specified element in the content is not found, an error is flagged. To avoid getting an error message in this case, set nocontent="ignore" attribute in the rule. Likewise specifying notheme="ignore" supresses error messages related to missing theme elements.

The top-level rules element may optionally contain the attribute debug="true" which causes comments to be inserted in the markup around elements that were inserted from the content by deliverance.

Except for the drop rule, any rule may contain the attribute move="true". When present, content matched by the rule will not be used by other rules.
If notheme="ignore" is specified when the move attribute is present and no theme element is matched, the element in the content remains available in the content to other rules. Rules containing the move attribute execute out of order after drop rules and before all other rules. Moving a node and then a parent of that node is
presently supported.

Any rule may optionally contain an attribute href which specifies an alternate resource from which to load this rule's content instead of the originally requested URI. This allows you to include content from other sources. The content attribute is still required, but now refers to elements in the referenced document.

Commands

replace

The element in the theme is replaced with the matching elements in the content. If no element is matched in the theme or content, an error is flagged. If more than one element in theme matches, an error is flagged. The xpath for the theme must point to elements, not just text.

copy

The element matched in the theme has all its children removed, and replaced with the matching elements in the content. If zero or more than one element in the theme is matched or no elements in the content are matched, an error is flagged.

append

The element in the theme has all the matching elements in the content appended (leaving any children elements that may have already been in the theme element). If zero or more than one element in the theme is matched or no elements in the content are matched, an error is flagged.

prepend

The element in the theme has all the matching elements in the content prepended (leaving any children elements that may have already been in the theme element). If zero or more than one element in the theme is matched or no elements in the content are matched, an error is flagged.

append-or-replace

The element in the theme has all the matching elements in the content appended. Any existing elements in the theme of the same tag type as the matched content elements are removed. The XPath for the content attribute must refer to a specific tag type like "/head/title" or ".//span[@id='foo']". If zero or more than one element in the theme is matched or no elements in the content are matched, an error is flagged.

drop

Any element in the theme page matching the xpath provided in the theme attribute of the rule is removed. Likewise, any element in the content page matching the xpath provided in the content attribute of the rule is removed. The xpath must point to elements, not just text. The drop rules are processed before any other rule.

XInclude in the Rules

The rules may contain infinitely-nested xincludes such as (where standardrules2.xml is another rules files):

<rules xmlns:xi="http://www.w3.org/2001/XInclude" xmlns="http://www.plone.org/deliverance">
<append-or-replace theme="//head" content="//head/title" />
<append theme="//head" content="//head/link" />
<xi:include href="standardrules2.xml" />
</rules>

Link Handling

Deliverance changes relative links in the theme and any Xincluded content to absolute links pointing to their original locations. Links are found in any attribute named "src" or "href" and the "url contained in an @import url(...)

<base href> usage in the content are preserved, <base href> usage in the theme are eliminated, but observed when rewriting relative urls.

The Head Element

Deliverance treats the <head> element like any other element. Generally it is useful to merge the <head> of both theme and content to some degree. Here are some useful examples for working with the <head> tags.

<title>

<append-or-replace theme="//head" content="//head/title" nocontent="ignore" />
The content title should take precedence.

<link>

<prepend theme="//head" content="//head/link" nocontent="ignore" />
All links from both theme and content should be included in the head. The links from the content are prepended before the links from the theme.

<script>

<append theme="//head" content="//head/script" nocontent="ignore" />
All scripts from both theme and content are included.

<style>

<prepend theme="//head" content="//head/style" nocontent="ignore" />
All inline stylesheets from both theme and content are included. The styles from the content are prepended before the styles from the theme.

<meta>

<append theme="//head" content="//head/meta" nocontent="ignore" />
The <meta> from the content are appended to the theme.

Foreign Character Encoding

Deliverance automatically removes <meta> tags with an http-equiv="content-type" attribute value from both the content and the theme. This eliminates conflicts in encoding (output is always "utf-8"). Deliverance only supports foreign character encodings that are specified in a <meta> tag that comes before any non-ASCII characters.