Synopsis more verbatim

WSGI deliverance configuration is intricate and extensive, and i struggle to tie together various bits as they are organized in thedeliverance configuration document [as of march, 2010]. so i distilled and often rephrased several parts, particularly those having to do with the transformation rules. i do not address proxy server settings.

the info is derived from v 0.3 of the Deliverance Configurationpage. that page includes many illuminating examples not included here.

(emacs table mode was terrifically handy for concocting the tables in the reStructuredText source for this document.)

what is python deliverance?

python deliverance is WSGI middleware (a web service application filtering layer) which applies rules that substitute html content elements into (usually) html theme templates.

see this (old but good) deliverance introduction for more background. see PloneWithWSGI for the context in which i'm exploring deliverance.

the configuration file elements

the deliverance configuration file dictates deliverance transformation and other operations using a set of xml elements within an encompassing <ruleset> element.

key terms

term	description
content	the page requested by the user
theme	the presentation layout within which elements of the content are deployed. typically the theme is also an HTML page.
rules	xml expressions which identify the way that content elements are substituted for theme elements.

---

the ruleset element

all the deliverance configuration file sections reside within a <ruleset> xml element:

<ruleset> <theme ...> <rule ...> <rule ...> ... <ruleset>

---

the theme element

the theme element identifies the page used as the theme layout code.

when a <theme> element resides at the top level of a <ruleset> element it specifies the overall default theme. when residing within a <rule> element, it applies just to that element's set of rules.

theme element	description
<theme href="/theme.html"/>	typically a URL, the target may be obtained with an internal request (eg, filesystem access?) if reachable that way, else via external web requests.
<theme pyref="mymodule:get_theme" />	theme references can also be pyref python references The default hook function name is get_theme.

---

the rule element

the <rule> element is a container for rule actions. the actions intersperse elements from the content within the theme.

• each rule can identify a particular page, distinct from the encompassing ruleset theme, by including a theme element.

• rules can be conditioned to apply to specific parts of a site using page classes andrequest/response matching,

• by default, the rule element includes several standard rule actions. these default actions can be suppressed by including suppress-standard="1" in the rule:

  <rule suppress-standard="1">.

rule actions

<replace ...>	replace something in the theme with something in the content
<append ...>	situate designated content after selected theme element. tag:(see below) doesn't work here.
<prepend ...>	situate selected content stuff before selected theme stuff.tag: (see below) doesn't work here.
<drop ...>	remove elements from the theme or content. drop actions do not require both content and theme attributes.

• the actions apply to target elements within the content and/or theme. these targets are designated using rule element selectors
• the rules take optional attributes <#optional_rule_attributes> which adjust their behavior.

rule element selectors

each action specifies target elements within the content and/or the theme using path expressions. there are two types of selector expression paths:

rule selector path type	description
CSS 3	does not start with a /, eg: <append content="#content" theme="#header" /> this would place the content element that has the id content after the theme element that has the id header.
!XPath	starts with a /. though !XPath can specify attributes, deliverance selectors are only concerned with elements.

rules act on the designated elements or entities related to those elements, according to selection target type. the selection target type is indicated as a prefix on the attribute value, eg <dropcontent="tag:ul">.

rule selection target types

selection target type	description
elements:	target the identified elements and their sub-elements. elements: is the default selection target type.
children:	target the offspring of the element, including text-content offspring.
attributes:	target just the attributes of the selected elements. you can narrow to particular named attributes; eg class and style usingattributes(class,style)
tag:	apply rule to the tag but not the tag's children. eg, <drop content="tag:..."> retains the tag's children, but removes the enclosing tag

not all selection target type combinations across theme and content make sense. eg you can't replace elements with attributes. generally, only elements: and children: work together.

you can specify fall-back selector target types by using the || operators, which yield the effect of the first selector that has a non-empty match.

• eg, content="#content || children:body" will match the element with the idcontent, if any, else all the children of <body>.
• || expressions can include both CSS and !XPath selectors.
• || expressions can only mix elements: and children: selection types

optional rule attributes

rule behavior can be further qualified with some optional attributes:

optional rule action attributes	values	effect
if-content=	selector, or selector prefixed withnot:	conditional rule operation - limit the action to content that matches both the rule'scontent=... selector and the value of theif-content attribute. an inverting not:qualifier is available, eg: if-content="not:.container".
move=	0 or 1 (default)	by default, rule actions effectively movedesignated elements from the content to the theme, ie, later rule actions don't see the affected content elements. to make the affected content available for subsequently fired rules, use move=0.
href=	URL	use the (potentially dynamic) document at URL instead of the originally requested page for this rule.

several optional rule action attributes adjust behavior when a selector does not match exactly one element, which is required for all the action types except for <drop>. the default handling is to log the problem at the level "warn", and for unexpected multiple matches, to log and use the first element. these are the four attributes to adjust the default behavior:

optional rule action attributes	values	effect
notheme=	abort, ignore	the handling when no theme elements are found. see the handling dispositions, below
manytheme=	abort, ignore, ignore:first, ignore:last	The handling when more than one theme element is found. see the handling dispositions, below
nocontent=	abort, ignore	the handling when no content elements are found. see the handling dispositions, below
manycontent=	abort, ignore, ignore:first, ignore:last	the handling when more than one content element is found, but that doesn't make sense in the context of the action. see the handling dispositions, below

many*= and no*=disposition qualifiers	qualifier effect
="ignore"	one of the candidate dispositions for the notheme/manytheme/nocontent/manycontent handling behaviors. when present, do not treat this as an error, and emit only a "debug" level logging message. when using ignore with the manycontent or manythemecontingencies, the first of the qualifying target elements is used by default. you can explicitly specify ="ignore:first" (default) or ="ignore:last" to use the first or last of the multiple qualifying elements.
="abort"	the other candidate disposition for the notheme/manytheme/nocontent/manycontent handling behaviors. when present, abandon theming of the requested page, instead presenting the unthemed content.

the deliverance documentation rule section includes more info, including particularly examples for each rule.

---

match and page classes

different sets of rules can be applied to different parts of a site by using page classes.

for example, for a page has the classes trac and default, these rules could be used:

<rule class="trac">...</rule> <rule class="default">...</rule>

• like CSS, any rules that match any of the classes on a page will be run
• like CSS, you can have multiple classes anywhere, separated by spaces
• unlike CSS, the classes are ordered, and define the run-order of the rules

page classes can be assigned in a few ways:

• via the server adding the response header X-Deliverance-Page-Class to identify each page's classes
• using deliverance' proxy server, adding a class attribute to proxy elements.
• using <match> configuration, discriminating class according to request/response matching on path or domain

request matching is described in request/response matching.

---

request/response matching

three deliverance configuration elements can be conditionally used according to request or response matches:

• <match>
• <rule>
• <proxy>

all these elements share common behavior and attributes.

several attributes can match against different parts of the request or response. when multiple attribute are provided then they must all match.

match type	match-target type	match-target pattern type	description
path=	string	path:	match the request path
domain=	string	wildcard-insensitive	match the domain name of the request URL
request-header=	key: value	key: wildcard; value: exact	matches key/value pairs in the web request
response-header=	key: value	key: wildcard; value: exact	matches key/value pairs in the web response
environ=	key: value	key: wildcard; value: exact	matches key/value pairs among the web evironment settings
pyref=	pyref	location:function_name	invoke a specific python function to handle the match

match-target type	description
string	a string that can be to matched against the target elements in one of several kinds ways. see the string pattern types table, below, for the pattern varieties.
key/value	: delimited key/value pairs, where the key is an * asterisk-style wildcard string pattern and the value part is an exact match.
pyref	various configuration elements can direct their operation to python functions, eg request response matching. see the deliverance python references page for details.

request/response matches often involve string patterns to be matched against the target document elements. there are several varieties of match operations, suited to different purposes, that can be employed. in cases where the the pattern type is optional (like the string match target type), the variety of pattern is indicated by prefixing one of the variety types (with the ':' colon) in front of the pattern, itself.

string match pattern type	description
wildcard:	'*' as a wildcard to match any length of characters in the target string
wildcard-insensitive:	like wildcard but the text matches can be of different alphabetic case than corresponding pattern characters
regex:	python regular expression
path:	match the string as a path prefix. like python string's starts-with, except it requires matches of the complete text between/'s. eg, path:/some-path will match /some-path/to/somewhere, /some-path/, and /some-path, but not /some-path-to-somewhere.
exact:	the target string must match the pattern character-for-character
exact-insensitive:	like exact, except the alphabetic case can vary
contains:	the target string must include the exact pattern string
contains-insensitive:	like contains, except the alphabetic case can vary
boolean:	the target string must be 1, true, yes, or on. boolean:notinverts the match.

---

proxy and server-settings

this section controls deliverance when it is deployed as a proxy server, affecting proxy destinations, server, and security settings.

i use paste rather than the deliverance proxy to incorporate deliverance, so have no experience with the proxy, and no info to offer beyond the link to the deliverance configuration proxy and server-settings section.

---

pyref python references

extend several elements by plugging in your own python functions via hooks.

---

debug reporting

deliverance can present some debugging info at the bottom of a visited page, if debugging is turned on. to see a trace of the deliverance actions at the bottom of a deliverance-transformed page, visit the url of the page with ?deliv_log appended. scroll down to the bottom of the page to see a table detailing the deliverance actions.