Deliverance Configuration ========================= .. contents:: All the configuration for Deliverance goes in an XML file. This file can configure page matches, transformation rules, proxying, and server settings. Though it is all in one file, there are several major sections. A quick overview: `theme`_: Determine the theme to apply to the page. `rule`_: Apply the actual transformations to the page by moving elements from the content into the theme. `match and page classes`_: In more complicated sites, page classes allow you to apply rules based on different criteria. `proxy and server-settings`_: Controls the proxy destinations, server, and security settings. `request/response matching`_: Several elements can be conditionally used only when the request or response matches conditions. All these elements share common behavior and attributes. `pyref Python references`_: Several elements can call Python hooks. This describes the general syntax, while the details of the hook are described alongside the element. `clientside theming`_: You can enable an experimental feature which will apply themes in the browser. Everything goes in a ```` tag. .. comment: FIXME: should this be ? The core function of Deliverance is to take a theme along with your content, and apply transformations. So we'll start there. theme ----- The ```` element defines the theme you'll be using. The theme is given as a URL. The basic form is: .. code-block:: xml This defines the theme as being at ``/theme.html``. If possible it will be fetched with an internal request, though external requests are also possible (if you host the theme outside of Deliverance). Scoped themes ~~~~~~~~~~~~~ If you have a ```` at the global level (in the ```` element) then that is the default theme. You can also put it inside ```` elements, and then it will apply just to that rule set. This is useful if you are using `match and page classes`_. In the case that multiple matching rule sets declare themes, the last theme seen is used. Pyref in themes ~~~~~~~~~~~~~~~ `The theme element also supports pyref `_ as an alternative to the ``href`` attribute. rule ---- The ```` element defines a set of transformations. It also supports `page classes`_ and `request/response matching`_, which you can read about in those sections. Also, as mentioned above, you can include a ```` element. But the most important thing is the transformation actions. Deliverance has a built-in set of default actions to take care of things like copying the document title and any ``script``, ``link`` and ``style`` attributes over. These rules can be suppressed by adding an ``suppress-standard='true'`` attribute on the ```` element. The transformation actions are applied in order. The starting point for the transformation is the *theme* document. The actions copy elements from the content into the theme. There are four actions: ````: Replaces something in the theme with elements from the content. ````: Appends content to an element in the theme. ````: Prepends content to an element in the theme. ````: Removes elements from the theme or the content. Selection and selection types ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Each rule depends on selecting elements from the theme and content. The most basic selection is done with CSS 3 selectors. For instance, this places the element in the content with the id ``content`` *after* the element in the theme with the id ``header``: .. code-block:: xml You can also use `XPath `_ selectors. Any selector starting with ``/`` is treated as an XPath expression, while everything else is treated as CSS. CSS can only select elements, and while XPath can select text or attributes Deliverance is only interested in elements. Moving elements around has some limitations, so there are different explicit types of selection: .. comment: FIXME: a better XPath link would be nice, like to a tutorial. ``elements:`` The default, this applies the rules to the elements selected. ``children:`` A common type, this applies rules to the *children* of the elements selected (including text content of the elements). ``attributes:`` This applies the rules to just the attributes. Also you can apply it to just specifically named attributes, for instance just to the ``class`` and ``style`` attributes with ``attributes(class,style):``. ``tag:`` This applies the rule to the tag, but not the children of the element. For instance, dropping a tag keeps the children in the document, but removes their enclosing tag. You can apply any of these like ``content="children:#content"``. Not all combinations make sense, and some are not allowed. For instance, ```` does not make sense, as you can't replace elements with attributes. Generally ``elements:`` and ``children:`` work together, ``attributes:`` only works with ``attributes:``, and ``tag:`` only works with ``tag:``. When selecting elements you can use the ``||`` operator. This applies to both CSS and XPath selectors, and with the operator you can mix the two. The ``||`` operator takes the results of the first selector that matches anything. So ``content="#content || children:body"`` will take the element ``#content`` if there is one, and if there is not one it will take all the children of ````. You can mix ``elements:`` and ``children:`` using ``||``, though no other types can be mixed like this. ```` ~~~~~~~~~~~~~ The ```` action replaces something in the theme with something in the content. Exactly what is replaced depends on the selection type. Some examples: .. code-block:: xml this replaces the elements *inside* the theme element ``#content`` with the elements inside the content element ``#content-wrapper``. The resulting document won't have any element with the id ``#content-wrapper`` (unless the theme already had an element with that id). .. code-block:: xml both of these are the same (``elements:`` is the default selection type). This replaces the theme element ``#content`` with the content element ``#content-wrapper``. The resulting document has no element ``#content``. .. code-block:: xml this removes all the attributes (e.g., ``class``, ``onload``) from the ```` element in the theme, and moves over the attributes from the content body element. .. code-block:: xml this replaces the tag ``#content`` in the theme with its corresponding tag from the theme. They might not be the same tag name (e.g., the theme might be a ``

`` and the content ``

``), and all attributes will be taken from the content. ```` and ```` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ These actions obviously are very similar; ```` puts things from te content after things in the theme, and ```` puts things from the content before things in the theme. Some examples: .. code-block:: xml this moves the children of the content element ``#sidenav`` to the end of the theme element ``#sidebar``, combining the navigation of the theme and content. If you wanted the content navigation to go first you'd use: .. code-block:: xml Another example: .. code-block:: xml this moves the children of ``#sidenav`` *after the element* with the element in the theme ``