Package: sk.recipe.xdv
This is aBuildoutrecipe that automates compilation ofXDVrules and theme
files intoXSLTfor use with transformation-capable web servers.IntroductionDeliveranceis a “game-changing” concept in the assembly and theming of
disparate web applications into singular, cohesive units.XDVis an
implementation of a subset of Deliverance that generates pure Extensible
Stylesheet Language (XSL) Transformation (XSLT) rules.Buildoutis 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 InformationProject home pagehttp://code.google.com/p/buildout-recipes/Source repositoryhttp://buildout-recipes.googlecode.com/svn/recipes/sk.recipe.xdvIssue trackerhttp://code.google.com/p/buildout-recipes/issues/listInstallationSince this is a Buildout recipe, there’s nothing really to install.  Just
mention the recipe name in a buildout and enjoy!  For example, yourbuildout.cfgmight 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, assuminghttpd.conf.templatecontains${my-theme:output}, the
generatedhttpd.confwill contain the path to the compiled XSLT file.Easy!Supported OptionsThesk.recipe.xdvrecipe 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’spartsdirectory named after the part in the buildout
configuration, and will create the compiled XSLT in that directory
namedtheme.xsl.includemode(Optional.) Tells how to de-reference content included by the rules,
defaults todocument.  Indocumentmode, included content is
inserted via the XSLTdocument()function.  Inssimode, it’s
by server-side include (and requires a compatible webserver).  Inesimode, 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 eithertrueorfalse.
Defaults to false if the Buildout itself is running in offline mode.If you don’t specify theoutputoption, 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}wherepart-nameis the
name of the part that used thesk.recipe.xdvrecipe.Example UsageFor this demonstration, we have pre-prepared rules and template files namedrules.xmlandtheme.htmlin thetestdatasubdirectory.  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,rulesandtheme, 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 namedtheme.xsland stuck it in a
subdirectory of the Buildout’s parts directory namedmy-rules, which
you’ll notice is the name of the part in thebuildout.cfgfile:>>> ls('parts', 'my-rules')
-  theme.xslWhat’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.Controlling the Destination FileThe default behavior of writing the compiled XSLT output to the parts
directory makes sense for most Buildout situations, but you may want further
control.  Let’s update thebuildout.cfgfile to do just that:>>> 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))Re-running the Buildout:>>> print system(buildout)
Uninstalling my-rules.
Installing my-rules.And now look what showed up in our working directory:>>> ls(destDir)
-  my-output.xslPerfect.Controlling 3rd-Party Entity InclusionXDV normally generates XSLT that translates content from an underlying
production system into the desired theme by applying the rules.  However,
content can also come from 3rd-party resources that are not part of the
current resource stream.  If you don’t tell in the rules file how to retrieve
them, then a default resource method will be used.  You can specify what that
default method should be using theincludemodeoption.Unless otherwise stated, the include mode uses the XSLTdocumentfunction.
You can be explicit about that by statingdocumentin the recipe’s part:[my-rules]
recipe = sk.recipe.xdv
includemode = document
...Other include modes aressito use server-side includes andesito use
edge-side includes.  Let’s give one of these a try.  First, let’s update thebuildout.cfg:>>> destDir = tmpdir('another-dir')
>>> docBased = join(destDir, 'doc-based.xsl')
>>> ssiBased = join(destDir, 'ssi-based.xsl')
>>> write(sample_buildout, 'buildout.cfg', '''
... [buildout]
... parts =
...     doc-based
...     ssi-based
...
... [doc-based]
... recipe = sk.recipe.xdv
... includemode = document
... output = %(docBased)s
... rules = %(rules)s
... theme = %(theme)s
...
... [ssi-based]
... recipe = sk.recipe.xdv
... includemode = ssi
... output = %(ssiBased)s
... rules = %(rules)s
... theme = %(theme)s
... ''' % dict(docBased=docBased, ssiBased=ssiBased, rules=rulesXML, theme=themeHTML))Now let’s run the Buildout and see how the output differs:>>> print system(buildout)
Uninstalling my-rules.
Installing doc-based.
Installing ssi-based.And now look what showed up in our working directory:>>> 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...ESI works similarly (if it really works at all; testing it this morning gives
me errors from the XDV compiler).Changelog0.0.0This release is destined to become the eventualGArelease.