Once you have written your rules file, you need to compile
it to an XSLT for deployment. In some cases, you may have an
application server that does this on the fly, e.g. if you
are using the
package with Plone. For deployment to a web server like
Apache or Nginx, however, you will need to perform this step
The easiest way to invoke the Diazo compiler is via the
command line script which is installed with the
egg. To see its help output, do:
$ bin/diazocompiler --help
To run the compiler with
$ bin/diazocompiler rules.xml
This will print the compiled XSLT file to the standard output. You can save it to a file instead using:
$ bin/diazocompiler -o theme.xsl -r rules.xml
The following command line options are available:
-t theme.htmlto supply a theme if none is specified in the rules.
-pto pretty-print the output for improved readability. There is a risk that this could alter rendering in the browser, though, as browsers are sensitive to some kinds of whitespace.
-ato set an absolute prefix - see below.
-ito set the default external file inclusion mode to one of
-nto permit fetching resources over a network.
--traceto output trace logging during the compilation step. This can be helpful in debugging rules.
Check the output of the
option for more details.
The compiler can be passed an "absolute prefix". This is a string that will be prefixed to any relative URL referenced an image, link or stylesheet in the theme HTML file, before the theme is passed to the compiler. This allows a theme to be written so that it can be opened and views standalone on the filesystem, even if at runtime its static resources are going to be served from some other location.
For example, say the theme is written with relative URLs
for images and external resources, such as
/>. When the compiled theme is applied to a live site, this
is unlikely to work for any URL other than a sibling of
Let's say the theme's static resources are served from a
simple web server and made available under the directory
/static. In this case, we can set an absolute prefix of
/static. This will modify the
tag in the compiled theme so that it becomes an absolute
path that will work for any URL:
Custom parameters may be passed in at runtime to enable
conditions for rules and theme selection. For this to
work, however, the compiled theme needs to be aware of the
to list the parameter names that should be known to the
theme. Multiple names should be separated by spaces. For
$ bin/diazocompiler -o theme.xsl -r rules.xml -c mode=test,preview
Here, the compiled theme will be aware of the parameters
$test. The default for
will be the string value
theme.xsl, it is now possible to pass these parameters. See the
section on Nginx deployment for more details about how to
do this with Nginx, or the next section for how to test it
Testing the compiled theme¶
To test the compiled theme, you can apply it to a static
file representing the content. The easiest way to do this
is via the
$ bin/diazorun --xsl theme.xsl content.html
This will print the output to the standard output. You can save it to a file instead with:
$ bin/diazorun -o output.html --xsl theme.xsl content.html
For testing, you can also compile and run the theme in one
go, by supplying the
(rules) argument to
$ bin/diazorun -o output.html -r rules.xml content.html
If you are using any custom parameters, you can specify string values for them on the command line:
- $ bin/diazorun -o output.html -r rules.xml
- -c mode=test,preview --parameters mode=live,preview=off content.html
To see the built-in help for this command, run:
$ bin/diazorun --help
Compiling the theme in Python code¶
You can run the Diazo compiler from Python code using the following helper function:
>>> from diazo.compiler import compile_theme
Please see the docstring for this function for more details about the parameters it takes.
returns an XSLT document in
format. To set up a transform representing the theme and
rules, you can do:
from lxml import etree from diazo.compiler import compile_theme absolute_prefix = "/static" rules = "rules.xml" theme = "theme.html" compiled_theme = compile_theme(rules, theme, absolute_prefix=absolute_prefix) transform = etree.XSLT(compiled_theme)
You can now use this transformation:
content = etree.parse(some_content) transformed = transform(content) output = etree.tostring(transformed)
Please see the
documentation for more details.