sk.recipe.xdv 0.0.0

Introduction

Deliverance is a “game-changing” concept in the assembly and theming of disparate web applications into singular, cohesive units. XDV is an implementation of a subset of Deliverance that generates pure Extensible Stylesheet Language (XSL) Transformation (XSLT) rules. Buildout is a civilized way of constructing of applications in repeatable a manner, driven by “recipes” that tell how to attain specific goals.

This recipe, sk.recipe.xdv, enables a Buildout to automatically construct the XSLT output of XDV from its source rules and theme.

Developer’s Information

Project home page

http://code.google.com/p/buildout-recipes/

Source repository

http://buildout-recipes.googlecode.com/svn/recipes/sk.recipe.xdv

Issue tracker

http://code.google.com/p/buildout-recipes/issues/list

Installation

Since this is a Buildout recipe, there’s nothing really to install. Just mention the recipe name in a buildout and enjoy! For example, your buildout.cfg might be something like this:

[buildout]
parts =
    my-webserver
    my-cms
    my-theme
    web-config
...
[my-theme]
recipe = sk.recipe.xdv
rules = ${buildout:directory}/etc/rules.xml
theme = ${buildout:directory}/src/skin/main-template.html
[web-config]
recipe = collective.recipe.template
input = ${buildout:directory}/etc/httpd.conf.template
output = ${buildout:directory}/etc/httpd.conf
...

Then, assuming httpd.conf.template contains ${my-theme:output}, the generated httpd.conf will contain the path to the compiled XSLT file.

Easy!

Supported Options

The sk.recipe.xdv recipe supports the following options:

rules

(Required.) The rules XML file to compile.

theme

(Required.) The theme HTML file to use as a template.

output

(Optional.) Where to write the XSLT file as a result of compilation. If not given, the recipe will create a subdirectory in the Buildout’s parts directory named after the part in the buildout configuration, and will create the compiled XSLT in that directory named theme.xsl.

includemode

(Optional.) Tells how to de-reference content included by the rules, defaults to document. In document mode, included content is inserted via the XSLT document() function. In ssi mode, it’s by server-side include (and requires a compatible webserver). In esi mode, it’s by edge-side include (and requires a compatible cache server).

network

(Optional.) Tells if it’s OK to access the network in order to resolve entities (fetch resources); specify either true or false. Defaults to false if the Buildout itself is running in offline mode.

If you don’t specify the output option, then this recipe sets it to the path of the generated theme XSLT file. You can then use that value in other parts of the buildout with ${part-name:output} where part-name is the name of the part that used the sk.recipe.xdv recipe.

Example Usage

For this demonstration, we have pre-prepared rules and template files named rules.xml and theme.html in the testdata subdirectory. Let’s grab some convenient references to these files:

>>> import os.path
>>> testdata = join(os.path.dirname(__file__), 'testdata')
>>> rulesXML = join(testdata, 'rules.xml')
>>> themeHTML = join(testdata, 'theme.html')

Now let’s make a buildout that compiles those rules and theme template:

>>> write(sample_buildout, 'buildout.cfg', '''
... [buildout]
... parts = my-rules
...
... [my-rules]
... recipe = sk.recipe.xdv
... rules = %(rules)s
... theme = %(theme)s
... ''' % dict(rules=rulesXML, theme=themeHTML))

We list the two required settings, rules and theme, and let Buildout do its thing:

>>> print system(buildout)
Installing my-rules.

Since we left every other option at the defaults, the recipe compiled the rules and template theme into a file named theme.xsl and stuck it in a subdirectory of the Buildout’s parts directory named my-rules, which you’ll notice is the name of the part in the buildout.cfg file:

>>> ls('parts', 'my-rules')
-  theme.xsl

What’s it look like? Let’s check:

>>> cat('parts', 'my-rules', 'theme.xsl') # doctest: +ELLIPSIS
<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform"...

That looks like XSLT to me.

>>> destDir = tmpdir('my-dir')
>>> destXSL = join(destDir, 'my-output.xsl')
>>> write(sample_buildout, 'buildout.cfg', '''
... [buildout]
... parts = my-rules
...
... [my-rules]
... recipe = sk.recipe.xdv
... output = %(destination)s
... rules = %(rules)s
... theme = %(theme)s
... ''' % dict(destination=destXSL, rules=rulesXML, theme=themeHTML))

>>> print system(buildout)
Uninstalling my-rules.
Installing my-rules.

>>> ls(destDir)
-  my-output.xsl

[my-rules]
recipe = sk.recipe.xdv
includemode = document
...

>>> print system(buildout)
Uninstalling my-rules.
Installing doc-based.
Installing ssi-based.

>>> ls(destDir)
-  doc-based.xsl
-  ssi-based.xsl
>>> cat(docBased) # doctest: +ELLIPSIS
<xsl:stylesheet ...<xsl:copy-of select="document('/legal.html', .)//*[@id = ...
>>> cat(ssiBased) # doctest: +ELLIPSIS
<xsl:stylesheet ... <xsl:copy-of select="/html/head/div[2]"/><xsl:comment># include  virtual="/legal.html...

Changelog

0.0.0

This release is destined to become the eventual GA release.