• Deliverance Introduction

last modified September 23, 2010 by garbas

 

 

Information on this page are old and are only kept because of history reasons.

Please follow link for more info about deliverance project: http://www.deliveranceproject.org/

 

 

 

-------------------------------------------------------------------------------------------------------------------


Motivation for Deliverance

Many online information systems excel in content production and content services like security, workflow, and searching.  These systems, however, lack a flexible way of theming this content for consumption by various audiences.

Zope, and Content Management System, for instance, forces web designers to learn a complex page templating language. It makes designing web pages slow to develop and hard to debug. There should be an easier way to take the content from a CMS and style it in various ways without understanding the architecture of the CMS and without even knowing the origin of the content. This would create a formal distinction between content production and content delivery.

Deliverance was designed to solve this problem.

Introducing Deliverance

Deliverance is a lightweight program that applies a theme to content according to a set of rules.It provides a quick and simple way to re-brand content from any mainstream content provider or technology.

An Introductory Example

Here is a quick example of Deliverance in action.  First we have a document that provides the content:

<html><body><div id="bar">Real Content</div></body></html>

And a document that provides the theme document we want to use to style the content:

<html><head><title>Blah</title></head><body><div id="foo">Dummy Content</div></body></html>

And now we write rules to tell Deliverance how to apply the theme to the content:

<replace theme="//div[@id='foo']" content="//div[@id='bar']" />

Which produces the following output:

<html><head><title>Blah</title></head><body><div id="bar">Real Content</div></body></html>

A Real-World Example

Suppose we wanted to take the content published on OpenPlans for the NYCSR project:

nycsr_content_thumb

And theme it using the NYCSR home page:

nycsr_theme_thumb

According to these rules:

<prepend theme="//head" content="//head/link" nocontent="ignore" />
<prepend theme="//head" content="//head/style" nocontent="ignore" />
<append theme="//head" content="//head/script" nocontent="ignore" />   
<append theme="//head" content="//head/meta" nocontent="ignore" />
<append-or-replace theme="//head" content="//head/title" nocontent="ignore" />
<copy theme="//div[@id='container']" content="//div[@id='region-content']/div[3]" />

You will get:

nycsr_out_thumb

Deliverance Components

Let's take a closer look at the components that make up Deliverance.

Content

The content is the information you want to style with the theme. It can be a live website or a static file, specified with a URI.

Theme

The theme contains the style and layout information you want to apply to the content. It can be a live website or a static file, specified with a URI.

Rules

The rules tell Deliverance how to apply the theme to the content. There are six types of rules: replace, copy, append, prepend, append-or-replace, and drop. The rules are specified in an xml document that looks like:

<?xml version="1.0" encoding="UTF-8"?>
<rules xmlns:xi="http://www.w3.org/2001/XInclude" xmlns="http://www.plone.org/deliverance" >
  <prepend theme="//head" content="//head/link" nocontent="ignore" />
  <prepend theme="//head" content="//head/style" nocontent="ignore" />
  <append theme="//head" content="//head/script" nocontent="ignore" />   
  <append theme="//head" content="//head/meta" nocontent="ignore" />
  <append-or-replace theme="//head" content="//head/title" nocontent="ignore" />
  <copy theme="//div[@id='container']" content="//div[@id='region-content']/div[3]" />
</rules>

Attributes in each rule contain XPath expressions that describe sections in the theme and content on which to perform the rule.  Other attributes control error handling and debugging information.

For a complete description of Deliverance, please see the Specification document.

Using Deliverance

There are currently three ways to use Deliverance: in a Command Line Transformation, as WSGI Middleware, and as a Proxy.

Command Line Transformation

The command line tool used to execute Deliverance is called deliverance-handtransform. For instructions, run:

deliverance-handtransform --help 

The theme, rules and other parameters are specified using command line options -t, -r, etc.  The result of the transform is output to standard out.

To avoid lengthy command lines, the tool can accept a "blend" file, using the -f flag, which describes the theme and rules to apply.

eg:

deliverance-handtransform -f ./blendfile.xml http://www.example.org

The second argument refers to the content; blendfile.xml contains something like:

<blend theme="http://www.example.org"
   baseurl="http://www.example.org"
   rules="./example-rules.xml" /> 

WSGI Middleware

Deliverance can also be used directly in a WSGI stack using the python class in deliverance.wsgifilter.DeliveranceMiddleware.  See deliverance/wsgifilter.py and deliverance/test_wsgi.py for examples.

Proxy

The deliverance proxy is a standalone application which serves a themed version of some web location using a theme and a set of rules.

eg:

deliverance-proxy --serve=localhost:5001 --proxy=localhost:8080
		  --theme=http://www.example.org
		  --rule=file:///some/path/somerulesfile.xml

This example provides a themed version of a local webserver at port 8080 served on port 5001. The theme page is http://www.example.org and the rules are specified in somerulesfile.xml.

For more options, run:

deliverance-proxy --help