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
plone.app.theming package with
Plone. For deployment to a web server like Apache or Nginx, however, you will
need to perform this step manually.
The easiest way to invoke the Diazo compiler is via the
command line script which is installed with the
diazo egg. To see its help
$ 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
--help 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
<img src="images/foo.jpg" />. When the
compiled theme is applied to a live site, this is unlikely to work for
any URL other than a sibling of the
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
<img /> tag
in the compiled theme so that it becomes an absolute path that will work for
<img src="/static/images/foo.jpg" />
Custom parameters may be passed in at runtime to enable advanced
conditions for rules and theme selection. For this to work, however, the
compiled theme needs to be aware of the possible parameters.
--custom-parameters option to
diazorun to list the parameter names that should be known to the theme.
Multiple names should be separated by spaces. For example:
$ 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
mode 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 with
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
-r (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.
compile_theme() 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
lxml documentation for more details.