i 10.3 Adding an attribute to elements...... 41 10.4 Modifying an attribute...... 43 10.5 Modifying text...... 43 10.6 Create an unordered list from a series of elements...... 44 10.7 Contributing a recipe...... 46
ii Diazo Documentation, Release 1.0b1
di-az-o (also di-az-o-type) noun a copying or coloring process using a diazo compound decomposed by ultraviolet light
Diazo allows you to apply a theme contained in a static HTML web page to a dynamic website created using any server-side technology. With Diazo, you can take an HTML wireframe created by a web designer and turn it into a theme for your favourite CMS, redesign the user interface of a legacy web application without even having access to the original source code, or build a unified user experience across multiple disparate systems, all in a matter of hours, not weeks. When using Diazo, you will work with syntax and concepts familiar from working with HTML and CSS. And by allowing you seamlessly integrate XSLT into your rule files, Diazo makes common cases simple and complex require- ments possible. Contents:
CONTENTS 1 Diazo Documentation, Release 1.0b1
2 CONTENTS CHAPTER ONE
INTRODUCTION
Consider a scenario where you have a dynamic website, to which you want to apply a theme built by a web designer. The web designer is not familiar with the technology behind the dynamic website, and so has supplied a static HTML wireframe of the site. This consists of an HTML file with more-or-less semantic markup, one or more style sheets, and perhaps some other resources like images or JavaScript files. Using Diazo, you could apply this theme to your dynamic website as follows: 1. Identify the placeholders in the theme file that need to be replaced with dynamic elements. Ideally, these should be clearly identifiable, for example with a unique HTML id attribute. 2. Identify the corresponding markup in the dynamic website. Then write a “replace” or “copy” rule using Diazo’s rules syntax that replaces the theme’s static placeholder with the dynamic content. 3. Identify markup in the dynamic website that should be copied wholesale into the theme. CSS and JavaScript links in the
are often treated this way. Write an Diazo “append” or “prepend” rule to copy these elements over. 4. Identify parts of the theme and/or dynamic website that are superfluous. Write an Diazo “drop” rule to remove these elements. The rules file is written using a simple XML syntax. Elements in the theme and “content” (the dynamic website) can be identified using CSS3 or XPath selectors. Once you have a theme HTML file and a rules XML file, you compile these using the Diazo compiler into a single XSLT file. You can then deploy this XSLT file with your application. An XSLT processor (such as mod_transform in Apache) will then transform the dynamic content from your website into the themed content your end users see. The transformation takes place on-the-fly for each request. Bear in mind that: • You never have to write, or even read, a line of XSLT (unless you want to). • The XSLT transformation that takes place for each request is very fast. • Static theme resources (like images, stylesheets or JavaScript files) can be served from a static webserver, which is normally much faster than serving them from a dynamic application. • You can leave the original theme HTML untouched, which makes it easier to re-use for other scenarios. For example, you can stitch two unrelated applications together by using a single theme file with separate rules files. This would result in two compiled XSLT files. You could use location match rules or similar techniques to choose which one to invoke for a given request. We will illustrate how to set up Diazo for deployment later in this guide.
3 Diazo Documentation, Release 1.0b1
4 Chapter 1. Introduction CHAPTER TWO
QUICKSTART
There are several ways to use Diazo: • If you want to theme Plone, you should use plone.app.theming • If you want to theme a Python WSGI application, you can use the WSGI middleware component described here and in more detail in Deployment. • If you want to theme just about anything, you can deploy a compiled theme to nginx or another web server To test Diazo, however, the easiest way is to set up a simple proxy. The idea is to run a local webserver that applies the Diazo theme to a response coming from an existing website, either locally or somewhere on the internet. To set up the proxy, we will use Buildout. 1. Create a directory for the buildout: $ mkdir diazo-test
2. Download the latest Buildout bootstrap.py and put it in this directory: $ cd diazo-test $ wget http://svn.zope.org/*checkout*/zc.buildout/trunk/bootstrap/bootstrap.py
3. Create a buildout.cfg in this directory with the following contents. Please read the inline comments and adjust your copy as necessary: [buildout] # Adjust the version number as required. See # http://good-py.appspot.com/release/diazo for a full list
4. Bootstrap the buildout (this is only required once): $ python bootstrap.py
Note: You should use a Python binary version 2.6 or above. Python 3 is currently untested and may not work. 5. Run the buildout (this is required each time you change buildout.cfg): $ bin/buildout
You should now have the binaries bin/paster, bin/diazocompiler, bin/diazorun and maybe a few others. 6. Place the theme in a directory. The theme is a static HTML design, usually with placeholder content and images, stylesheets and JavaScript resources included via relative links. You would normally be able to test the theme by opening it from the filesystem. For the purposes of this quick-start guide, we’ll create a very simple theme: $ mkdir theme
In the theme directory, we place a theme.html:
My own Diazo
My own Diazo home page
Lorem ipsum ...
We also create theme.css: h1 { font-size: 18pt; font-weight: bold; }
7. Create the rules file. The rules file contains the Diazo directives that merge the content (the thing we are applying the theme to) into the theme, replacing placeholders with real content. For this example, we’ll theme diazo.org, copying in the .content area and dropping the indices and tables. We create rules.xml at the top level (next to buildout.cfg):
See Basic syntax for details about the rules syntax. Hint: Use tools like Firefox’s Firebug or Chrome’s Developer Tools to inspect the theme and content pages, looking for suitable ids and classes to build the rules from. 8. Create the configuration file for the proxy server. This uses the Paste Deploy toolset to set up a WSGI applica- tion. At the top level (next to buildout.cfg), we create proxy.ini: [server:main] use = egg:Paste#http host = 0.0.0.0 port = 5000
[composite:main] use = egg:Paste#urlmap /static = static / = default
# Serve the theme from disk from /static (as set up in [composite:main]) [app:static] use = egg:Paste#static document_root = %(here)s/theme
# Reference the rules file and the prefix applied to relative links # (e.g. the stylesheet). We turn on debug mode so that the theme is # re-built on each request, making it easy to experiment.
# Proxy http://diazo.org as the content [app:content]
7 Diazo Documentation, Release 1.0b1
use = egg:Paste#proxy address = http://diazo.org/ suppress_http_headers = accept-encoding
9. Run the proxy: $ bin/paster serve --reload proxy.ini
10. Test, by opening up http://localhost:5000/ in your favourite web browser.
8 Chapter 2. Quickstart CHAPTER THREE
INSTALLATION
To install Diazo, you should install the diazo Python distribution. Note: The Diazo package is only required to get the Diazo compiler and development tools. If you deploy your Diazo theme into a web server, you do not need the diazo distribution on that server. You can install the diazo distribution using easy_install, pip or zc.buildout. For example, using easy_install (ideally in a virtualenv): $ easy_install -U diazo
If using zc.buildout, you can use the following buildout.cfg as a starting point. This will ensure that the console scripts are installed, which is important if you need to execute the Diazo compiler manually: [buildout] parts = diazo
[diazo] recipe = zc.recipe.egg eggs = diazo
Note that lxml is a dependency of diazo, so you may need to install the libxml2 and libxslt development packages in order for it to build. On Debian/Ubuntu you can run: $ sudo apt-get install build-essential python2.6-dev libxslt1-dev
On some operating systems, notably Mac OS X, CentOS and other RedHat-based Linux distributions, installing a “good” lxml egg can be problematic, due to a mismatch in the operating system versions of the libxml2 and libxslt libraries that lxml uses. To get around that, you can compile a static lxml egg using the following buildout recipe: [buildout] # lxml should be first in the parts list parts = lxml diazo
[lxml] recipe = z3c.recipe.staticlxml egg = lxml
[diazo] recipe = zc.recipe.egg eggs = diazo
9 Diazo Documentation, Release 1.0b1
Once installed, you should find diazocompiler and diazorun in your bin directory. If you want to use the WSGI middleware filter, you should use the [wsgi] extra when installing the Diazo egg. See Quickstart for an example.
10 Chapter 3. Installation CHAPTER FOUR
BASIC SYNTAX
A Diazo theme consists of a static HTML page (referred to as the “theme”) and a rules file, conventionally called rules.xml. The rules file contains an XML document that is is rooted in a tag called :
...
Here we have defined three namespaces: the default namespace is used for rules and XPath selectors. The css namespace is used for CSS3 selectors. These are functionally equivalent to the XPath selectors. In fact, CSS selectors are replaced by the equivalent XPath selector during the pre-processing step of the compiler. Thus, they have no performance impact. The xsl namespace is used if you want to add inline XSLT directives for fine-grained control. We will come to that later in this guide. Diazo supports complex CSS3 and XPath selectors, including things like the nth-child pseudo- selector. You are advised to consult a good reference if you are new to XPath and/or CSS3.
4.1 Rule directives
The following directives are allowed inside the element in the rules file:
4.1.1
Used to specify the theme file. For example:
Relative paths are resolved relative to the rules.xml file. For http/https urls, the --network switch must be supplied to the diazocompiler or diazorun program. The following attributes are allowed: href (required) A reference to the theme HTML file, as either a relative or absolute URL. if Used to specify an arbitrary condition that must be true for this theme reference to be used. More on this in the section on using multiple themes later in this guide.
11 Diazo Documentation, Release 1.0b1
if-path Used to specify a URL path segment that must be matched by the current request for this theme reference to be used. More on this in the section on using multiple themes later in this guide. if-content or css:if-content Used to specify an element that must be present in the content for this theme reference to be used. More on this in the section on using multiple themes later in this guide.
4.1.2
Used to turn off all theming in certain conditions. For example:
Multiple elements may be used. If the condition on any of them is true, the theme will be omitted. That is, they are logically or’d together. One or more of the following attributes are required: if Used to specify an arbitrary condition for when to omit the theme. if-path Used to specify a URL path segment that must be matched by the current request for the theme to be omitted. if-content or css:if-content Used to specify an element that must be present in the content for the theme to be omitted. If more than one attribute is used, the condition of all must be true for the directive to take effect. That is, they are logically and’ed together.
4.1.3
Used to replace an element in the theme entirely with an element in the content. For example:
The (near-)equivalent using CSS selectors would be:
The result of either is that the
element in the theme is replaced with the element in the (dynamic) content. The following attributes are allowed: theme or theme-children or css:theme or css:theme-children (required) Used to specify the node(s) in the theme that is to be replaced. When using theme-children, all elements inside the tag that matches the XPath or CSS expression will be replaced, but the matched tag itself will remain intact. content or content-children or css:content or css:content-children (required) Used to specify the node in the content that is to replace the matched node(s) in the theme. When using content-children, all elements inside the tag that matches the XPath or CSS expression will be used, but the matched tag itself will be left out. attributes If you want to replace attributes instead of tags, you can use the attributes attribute to provide a space-separated list of attributes that should be replaced on the matched theme node(s). For example, with attributes="class" the class attribute on the matched theme node(s) will be replaced by the class attribute of the matched content node(s).
Note: As with rules working on tags, if the named attribute(s) do not exist on the both the theme and content nodes, nothing will happen. If you want to copy attributes regardless of whether they exist on the theme node(s) or not, you can use instead. Using attributes="class id", the class and id attributes will be replaced. As a special case, you can write attributes="*" to drop all attributes on the matched theme node and copy over all attributes from the matched content node. Note: You should not use theme-children or content-children or their CSS equivalents when using attributes. See also , and method If you have any or other rules that manipulate the content, and you do not want that manipulation to be taken into account when performing this replacement, you can add method="raw" to the rule. if Used to specify an arbitrary condition for when to perform the replacement. if-path Used to specify a URL path segment that must be matched by the current request for the replacement to be performed if-content or css:if-content Used to specify an element that must be present in the content for the replace- ment to be performed. For more advanced usage of , see Modifying the theme on the fly and Modifying the content on the fly.
4.1.4 and
These are equivalent to except that the node(s) matched in the content are inserted before or after the node(s) matched in the theme, respectively. For example:
This would place the element with id info-box from the content immediately before the element with id content in the theme. If we wanted the box below the content instead, we could do:
To insert the box immediately inside the #content node, before any of its existing children, we could do:
and have the same required and optional attributes as , except for attributes, which is not supported.
4.1.5
Used to drop elements from the theme or the content. This is the only element that accepts either theme or content attributes (or their css: and -children equivalents), but not both:
This would copy all children of the element with id portal-content in the theme into the element with id content in the theme, but only after removing any element with class about-box inside the content element first. Similarly:
Would drop the tag from the head of the theme. The following attributes are allowed: theme or theme-children or css:theme or css:theme-children Used to specify the node(s) in the theme that is to be dropped. When using theme-children, all elements inside the tag that matches the XPath or CSS expression will be dropped, but the matched tag itself will remain intact. content or content-children or css:content or css:content-children Used to specify the node(s) in the content that is to be dropped. When using content-children, all elements inside the tag that matches the XPath or CSS expression will be dropped, but the matched tag itself will remain intact. attributes If you want to drop attributes instead of whole tags, you can use the attributes attribute to pro- vide a space-separated list of attributes that should be dropped on the matched theme node(s). For exam- ple, with attributes="class" the class attribute will be dropped from the matched node(s). Using attributes="class id", the class and id attributes will both be dropped. As a special case, you can write attributes="*" to drop all attributes on the matched theme node. Note: You should not use theme-children or content-children or their CSS equivalents when using attributes. See also and if Used to specify an arbitrary condition for when to perform the drop. if-path Used to specify a URL path segment that must be matched by the current request for the drop to be performed if-content or css:if-content Used to specify an element that must be present in the content for the drop to be performed.
4.1.6
Used to strip a tag from the theme or content, leaving its children intact. You can think of this as the inverse of with theme-children or content-children. For example:
This will remove the element with id content, leaving in place all its children. Similarly:
This will replace the theme’s element with the id content-area with the element in the content that has the id main-area, but will strip out any nested tags with the CSS class wrapper found inside #main-area. uses the same attributes and semantics as .
4.1.7
Used to merge the values of attributes in the content with attributes with the same name in the theme. This is mainly useful for merging CSS classes:
The following attributes are allowed: attributes (required) A space-separated list of attributes to merge. A given attribute must exist on both the theme and the content nodes for the rule to have any effect. theme or css:theme (required) The theme node(s) to merge the attribute value(s) with. content (required) The content node(s) to merge the attribute value(s) from. separator The separator to use when merging attributes. The default is to use a space. Use separator="" to merge with no separator. if Used to specify an arbitrary condition for when to perform the merge. if-path Used to specify a URL path segment that must be matched by the current request for the merge to be performed if-content or css:if-content Used to specify an element that must be present in the content for the merge to be performed.
4.1.8
Used to copy an attribute from a node in the content to a node in the theme. Unlike , will work even if the attribute does not exist on the target theme node. If it does exist, it will be replaced. For example:
The following attributes are allowed: theme or css:theme (required) Used to specify the node(s) in the theme where the attribute should be copied. content or css:content (required) Used to specify the node(s) in the content from which the attribute should be copied. attributes (required) A space-separated list of attributes that should be copied to the theme. As a special case, you can write attributes="*" to drop all attributes on the matched theme node and copy over all attributes from the matched content node. if Used to specify an arbitrary condition for when to perform the copy. if-path Used to specify a URL path segment that must be matched by the current request for the copy to be performed if-content or css:if-content Used to specify an element that must be present in the content for the copy to be performed.
In most cases, you should not care too much about the inner workings of the Diazo compiler. However, it can some- times be useful to understand the order in which rules are applied. 1. rules using theme (but not theme-children) are always executed first. 2. rules are executed next. 3. rules using theme (but not theme-children) are executed next, provided no rule was applied to the same theme node or method="raw" was used. 4. rules are executed next. Note that rules do not prevent other rules from firing, even if the content or theme node is going to be stripped. 5. Rules that operate on attributes. 6. and and rules using theme-children execute next, provided no rule using theme was applied to the same theme node previously. 7. rules using theme (but not theme-children) are executed last.
4.3 Behaviour if theme or content is not matched
If a rule does not match the theme (whether or not it matches the content), it is silently ignored. If a rule matches the theme, but not the content, the matched element will be dropped in the theme:
Here, if the element with id header-element is not found in the content, the placeholder with id header in the theme is removed. Similarly, the contents of a theme node matched with a rule will be dropped if there is no matching content. Another way to think of this is that if no content node is matched, Diazo uses an empty nodeset when copying or replacing. If you want the placeholder to stay put in the case of a missing content node, you can make this a conditional rule:
See the next section for more details on conditional rules.
16 Chapter 4. Basic syntax CHAPTER FIVE
ADVANCED USAGE
For most themes, the basic rules will suffice. There are times when you need a little more power, however, for example when working with a complex design or a content source that does not have well-defined, semantic markup.
5.1 Conditional rules
Sometimes, it is useful to apply a rule only if a given element appears or does not appear in the markup. The if, if-content and if-path attributes can be used with any rule, as well as the and direc- tives.
5.1.1 Conditions based on content nodes
if-content should be set to an XPath expression. You can also use css:if-content with a CSS3 expression. If the expression matches a node in the content, the rule will be applied:
This will copy all elements with class portlet into the portlets element. If there are no matching elements in the content we drop the portlet-wrapper element, which is presumably superfluous. Here is another example using CSS selectors:
This will copy the children of the element with id header-box in the content into the element with id header in the theme, so long as an element with id personal-bar also appears somewhere in the content. An empty if-content (or css:if-content) is a shortcut meaning “use the expression in the content or css:content‘ attribute as the condition”. Hence the following two rules are equivalent:
If multiple rules of the same type match the same theme node but have different if-content expressions, they will be combined as an if..else if...else block:
17 Diazo Documentation, Release 1.0b1
These rules all attempt to fill the text in the
inside the body. The first rule looks for a similar tag and uses its text. If that doesn’t match, the second rule looks for any with id first-heading, and uses its text. If that doesn’t match either, the final rule will be used as a fallback (since it has no if-content), taking the contents of the tag in the head of the content document. A content condition may be negated with if-not-content or css:if-not-content, for example:
5.1.2 Conditions based on paths
Provided the live transform is correctly configured to pass the relevant parameter (the $path parameter), it is possible to create conditions based on URL path segments in the incoming request. This uses the if-path attribute. A leading / indicates that a path should be matched at the start of the url:
matches pages with urls /news, /news/ and /news/page1.html but not /newspapers - only complete path segments are matched. A trailing / indicates that a path should be matched at the end of the url:
matches /mysite/news and /mysite/news/. To match an exact url, use both leading and trailing /:
matches /news and /news/. Without a leading or trailing / the path segment(s) may match anywhere in the url:
matches /mysite/news/space/page1.html. Multiple alternative path conditions may be included in the if-path attribute as whitespace separated list:
matches / and /index.html. if-path="/" is considered an exact match condition A path condition may be negated with if-not-path, for example:
5.1.3 Conditions based on arbitrary parameters
The if attribute can be used to make a rule or theme conditional on any valid XPath expression. For example, if the transform is set up to receive a string parameter $mode, you could write:
Use the if-not attribute to negate the conditon, for example:
5.1.4 Condition grouping and nesting
A condition may be applied to multiple rules by placing it on a tag:
...
Conditions may also be nested, so:
Is equivalent to:
5.1.5 Multiple, conditional themes
It’s possible to specify multiple themes using conditions. For instance:
Potential themes are tested in the order specified. The first one to match is used. The unconditional theme is used as a fallback when no other theme’s condition is satisfied. If no unconditional theme is specified, the document is passed through without theming. It is also possible to conditionally disable theming, using :
The theme is disabled if there is a matching , regardless of any conditional directives. All rules are applied to all themes. To have a rule apply to only a single theme, use the condition grouping syntax:
Sometimes, the theme is almost perfect, but cannot be modified, for example because it is being served from a remote location that you do not have access to, or because it is shared with other applications. Diazo allows you to modify the theme using “inline” markup in the rules file. You can think of this as a rule where the matched content is explicitly stated in the rules file, rather than pulled from the response being styled. For example:
In the example above, the rule will copy the attribute and its contents into the
of the theme. Similar rules can be constructed for and . It is even possible to insert XSLT instructions into the compiled theme in this manner:
Here, the XSL context is the root node of the content. Notice how we used css:select to select a node to operate on in the directive. In fact, you can use the css: namespace for anything that specifies an XPath expression, and the Diazo pre-processor will turn it into the equivalent XPath for you. Inline markup and XSLT may be combined with conditions:
Welcome to our new blog
5.3 Modifying the content on the fly
It is possible to modify the included content using . For example:
This may be combined with conditions and inline XSLT.
5.4 Inline XSL directives
You may supply inline XSL directives in the rules to tweak the final output. For instance to strip space from the output document use:
(Note: this may effect the rendering of the page on the browser.) Inline XSL directives must be placed directly inside the root tag and are applied unconditionally.
5.5 Doctypes
By default, Diazo transforms output pages with the XHTML 1.0 Transitional doctype. To use a strict doctype include this inline XSL:
It’s important to note that only the XHTML 1.0 Strict and XHTML 1.0 Transitional doctypes trigger the special XHTML compatibility mode of libxml2’s XML serializer. This ensures is rendered as and
as , which is necessary for browsers to correctly parse the document as HTML. It’s not possible to set the HTML5 doctype from XSLT, so plone.app.theming and the included WSGI middleware include a doctype option which may be set to “”.
5.6 XInclude
You may wish to re-use elements of your rules file across multiple themes. This is particularly useful if you have multiple variations on the same theme used to style different pages on a particular website. Rules files may be included using the XInclude protocol. Inclusions use standard XInclude syntax. For example:
Normally, the content attribute of any rule selects nodes from the response being returned by the underlying dy- namic web server. However, it is possible to include content from a different URL using the href attribute on any rule (other than ). For example:
This will resolve the URL /extra.html, look for an element with id portlet and then append to to the element with id left-column in the theme. The inclusion can happen in one of three ways:
5.7.1 Using the XSLT document() function.
This is the default, but it can be explicitly specified by adding an attribute method="document" to the rule element. Whether this is able to resolve the URL depends on how and where the compiled XSLT is being executed:
5.7.2 Using a Server Side Include directive
This can be specified by setting the method attribute to ssi:
The output will render like this:
This SSI instruction would need to be processed by a fronting web server such as Apache or Nginx. Also note the ;filter_xpath query string parameter. Since we are deferring resolution of the referenced document until SSI processing takes place (i.e. after the compiled Diazo XSLT transform has executed), we need to ask the SSI processor to filter out elements in the included file that we are not interested in. This requires specific configuration. An example for Nginx is included below. For simple SSI includes of a whole document, you may omit the content selector from the rule:
The output then renders like this:
Some versions of Nginx have required the wait="yes" ssi option to be stable. This can be specified by setting the method attribute to ssiwait.
5.7.3 Using an Edge Side Includes directive
This can be specified by setting the method attribute to esi:
Again, the directive would need to be processed by a fronting server, such as Varnish. Chances are an ESI-aware cache server would not support arbitrary XPath filtering. If the referenced file is served by a dynamic web server, it may be able to inspect the ;filter_xpath parameter and return a tailored response. Otherwise, if a server that can be made aware of this is placed in-between the cache server and the underlying web server, that server can perform the necessary filtering. For simple ESI includes of a whole document, you may omit the content selector from the rule:
The output then renders like this:
5.7. Including external content 23 Diazo Documentation, Release 1.0b1
24 Chapter 5. Advanced usage CHAPTER SIX
COMPILATION
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 diazocompiler command line script which is installed with the diazo egg. To see its help output, do: $ bin/diazocompiler --help
To run the compiler with rules.xml: $ 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: • Use -t theme.html to supply a theme if none is specified in the rules. • Use -p to 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. • Use -a to set an absolute prefix - see below. • Use -i to set the default external file inclusion mode to one of document, ssi or esi. • Use -n to permit fetching resources over a network. • Use --trace to output trace logging during the compilation step. This can be helpful in debugging rules. Check the output of the --help option for more details.
6.1 Absolute prefix
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 the images folder.
25 Diazo Documentation, Release 1.0b1
Let’s say the theme’s static resources are served from a simple web server and made available under the di- rectory /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:
6.2 Custom parameters
Custom parameters may be passed in at runtime to enable advanced if conditions for rules and theme selection. For this to work, however, the compiled theme needs to be aware of the possible parameters. Use the -c / --custom-parameters option to diazocompiler and 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 $mode and $test. The default for mode will be the string value test. Using this 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 diazorun.
6.3 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 diazorun script: $ 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 diazorun: $ 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
6.4 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 lxml‘s ElementTree format. To set up a transform repre- senting 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.
6.4. Compiling the theme in Python code 27 Diazo Documentation, Release 1.0b1
28 Chapter 6. Compilation CHAPTER SEVEN
DEPLOYMENT
Before it can be used, the deployed theme needs to be deployed to a proxying web server which can apply the XSLT to the response coming back from another web application. In theory, any XSLT processor will do. In practice, however, most websites do not produce 100% well-formed XML (i.e. they do not conform to the XHTML “strict” doctype). For this reason, it is normally necessary to use an XSLT processor that will parse the content using a more lenient parser with some knowledge of HTML. libxml2, the most popular XML processing library on Linux and similar operating systems, contains such a parser.
7.1 Plone
If you are working with Plone, the easiest way to use Diazo is via the plone.app.theming add-on. This provides a control panel for configuring the Diazo rules file, theme and other options, and hooks into a transformation chain that executes after Plone has rendered the final page to apply the Diazo transform. Even if you intend to deploy the compiled theme to another web server, plone.app.theming is a useful develop- ment tool: so long as Zope is in “development mode”, it will re-compile the theme on the fly, allowing you to make changes to theme and rules on the fly. It also provides some tools for packaging up your theme and deploying it to different sites.
7.2 WSGI
Diazo ships with two WSGI middleware filters that can be used to apply the theme: • XSLTMiddleware, which can apply a compiled theme created with diazocompiler • DiazoMiddleware, which can be used to compile a theme on the fly and apply it. In most cases, you will want to use DiazoMiddleware, since it will cache the compiled theme. In fact, it uses the XSLTMiddleware internally. See Quickstart for an example of how to set up a WSGI pipeline using the DiazoMiddleware filter, which is exposed to Paste Deploy as egg:diazo. You can use egg:diazo#xslt for the XSLT filter. The following options can be passed to XSLTMiddleware: filename A filename from which to read the XSLT file tree A pre-parsed lxml tree representing the XSLT file filename and tree are mutually exclusive. One is required. read_network Set this to True to allow resolving resources from the network. Defaults to False.
29 Diazo Documentation, Release 1.0b1
update_content_length Can be set to False to avoid calculating an updated Content-Length header when applying the transformation. This is only a good idea if some middleware higher up the chain is going to set the content length instead. Defaults to True. ignored_extensions Can be set to a list of filename extensions for which the transformation should never be applied. Defaults to a list of common file extensions for images and binary files. environ_param_map Can be set to a dict of environ keys to parameter names. The corresponding values in the WSGI environ will then be sent to the transformation as parameters with the given names. Additional arguments will be passed to the transformation as parameters. When using Paste Deploy, they will always be passed as strings. The following options can be passed to DiazoMiddleware: rules Path to the rules file theme Path to the theme, if not specified using a directive in the rules file. May also be a URL to a theme served over the network. debug If set to True, the theme will be recompiled on every request, allowing changes to the rules to be made on the fly. Defaults to False. prefix Can be set to a string that will be prefixed to any relative URL referenced in 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, an can be turned into with a prefix of “/static”. includemode Can be set to ‘document’, ‘esi’ or ‘ssi’ to change the way in which includes are processed read_network Set this to True to allow resolving resources from the network. Defaults to False. update_content_length Can be set to False to avoid calculating an updated Content-Length header when applying the transformation. This is only a good idea if some middleware higher up the chain is going to set the content length instead. Defaults to True. ignored_extensions Can be set to a list of filename extensions for which the transformation should never be applied. Defaults to a list of common file extensions for images and binary files. environ_param_map Can be set to a dict of environ keys to parameter names. The corresponding values in the WSGI environ will then be sent to the transformation as parameters with the given names. When using DiazoMiddleware, the following keys will be added to the WSGI environ: diazo.rules The path to the rules file. diazo.absolute_prefix The absolute prefix as set with the prefix argument diazo.path The path portion of the inbound request, which will be mapped to the $path rules variable and so enables if-path expressions. diazo.query_string The query string of the inbound request, which will be available in the rules file as the variable $query_string. diazo.host The inbound hostname, which will be available in the rules file as the variable $host. diazo.scheme The request scheme (usually http or https), which will be available in the rules file as the variable $scheme.
To deploy an Diazo theme to the Nginx web server, you will need to compile Nginx with a special version of the XSLT module that can (optionally) use the HTML parser from libxml2. In the future, the necessary patches to enable HTML mode parsing will hopefully be part of the standard Nginx distribution. In the meantime, they are maintained in the html-xslt project. Using a properly patched Nginx, you can configure it with XSLT support like so: $ ./configure --with-http_xslt_module
If you are using zc.buildout and would like to build Nginx, you can start with the following example: [buildout] parts = ... Nginx
If libxml2 or libxslt are installed in a non-standard location you may need to supply the --with-libxml2= and --with-libxslt= options. This requires that you set an appropriate LD_LIBRARY_PATH (Linux / BSD) or DYLD_LIBRARY_PATH (Mac OS X) environment variable when running Nginx. For theming a static site, enable the XSLT transform in the Nginx configuration as follows: location / { xslt_stylesheet /path/to/compiled-theme.xsl path=’$uri’ ; xslt_html_parser on; xslt_types text/html; }
Notice how we pass the path parameter, which will enable if-path expressions to work. It is possible to pass additional parameters to use in an if condition, provided the compiled theme is aware of these. See the previous section about the compiler for more details. Nginx may also be configured as a transforming proxy server: location / { xslt_stylesheet /path/to/compiled-theme.xsl path=’$uri’ ; xslt_html_parser on; xslt_types text/html;
Removing the Accept-Encoding header is sometimes necessary to prevent the backend server compressing the re- sponse (and preventing transformation). The response may be compressed in Nginx by setting gzip on; - see the gzip module documentation for details. In this example an X-Diazo header was set so the backend server may choose to serve different different CSS resources.
7.3.1 Including external content with SSI
As an event based server, it is not practical to add document() support to the Nginx XSLT module for in-transform inclusion. Instead, external content is included through SSI in a sub-request. The SSI sub-request includes a query string parameter to indicate which parts of the resultant document to include, called ;filter_xpath - see above for a full example. The configuration below uses this parameter to apply a filter: worker_processes 1; events { worker_connections 1024; } http { include mime.types; gzip on; server { listen 80; server_name localhost; root html;
# Decide if we need to filter if ($args ~ "^(.*);filter_xpath=(.*)$") { set $newargs $1; set $filter_xpath $2; # rewrite args to avoid looping rewrite ^(.*)$ /_include$1?$newargs?; }
location / { xslt_stylesheet theme.xsl path=’$uri’ ; xslt_html_parser on; xslt_types text/html; ssi on; # Not required in ESI mode } } }
In this example the sub-request is set to loop back on itself, so the include is taken from a themed page. filter.xsl (in the lib/diazo directory) and theme.xsl should both be placed in the same directory as Nginx.conf. An example buildout is available in Nginx.cfg in this package.
7.4 Varnish
To enable ESI in Varnish simply add the following to your VCL file: sub vcl_fetch { if (obj.http.Content-Type ~ "text/html") { esi; } }
An example buildout is available in varnish.cfg in the Diazo distribution.
7.5 Apache
Diazo requires a version of mod_transform with html parsing support. The latest compatible version may be downloaded from the html-xslt project page. As well as the libxml2 and libxslt development packages, you will require the appropriate Apache development pack- age: $ sudo apt-get install libxslt1-dev apache2-threaded-dev
(or apache2-prefork-dev when using PHP.) Install mod_transform using the standard procedure: $ ./configure $ make $ sudo make install
The ApacheFS directive enables XSLT document() inclusion, though beware that the includes documents are currently parsed using the XML rather than HTML parser. Unfortunately it is not possible to theme error responses (such as a 404 Not Found page) with Apache as these do not pass through the filter chain. As parameters are not currently supported, path expression are unavailable.
34 Chapter 7. Deployment CHAPTER EIGHT
CONTRIBUTING TO THIS DOCUMENTATION
Contributing to this documentation is easy, just follow these steps*: 1. Install Sphinx. 2. Fork the github repository at https://github.com/plone/diazo. If you don’t know how to do it, check Fork a Repo at GitHub Help. 3. Check out the repository you just forked: $ git clone https://github.com/YOUR-GITHUB-USERNAME/diazo
4. Change directories to the documentation directory: $ cd diazo/docs
5. Make your changes. If you don’t know Sphinx or reStructuredText, you can read about them respectively here, and here. To see the final result you can run: $ make html
6. Commit your changes and push them back to your github fork: $ git commit -m ’Added documentation to make the world a better place’ $ git push origin master
7. Send a pull request with your changes. See how in Send Pull Requests at GitHub Help.
35 Diazo Documentation, Release 1.0b1
36 Chapter 8. Contributing to this documentation CHAPTER NINE
CONTRIBUTING TO DIAZO
Diazo is maintained by the Plone project. The canonical source code repository can be found at: https://github.com/plone/diazo
You can follow the same fork & pull request procedure described above to contribute to the source. Discussion about the development of Diazo happens mainly on the plone-developers mailing list. If you have questions as a user of Diazo, please see http://plone.org/support. Some important ground rules: • Please do each new features on a separate branch. Bugfixes can be done in the master branch. • Keep the tests passing and write new tests (simply create a new directory in the tests/ directory following the convention of the existing tests).
37 Diazo Documentation, Release 1.0b1
38 Chapter 9. Contributing to Diazo CHAPTER TEN
RECIPES
10.1 Drop empty tags
This recipe demonstrates dropping of empty paragraph tags, including those that contain only whitespace or a single non-breaking space.
10.1.1 Rules
10.1.2 Theme
Content
10.1.3 Content
39 Diazo Documentation, Release 1.0b1
Not empty paragraph text
Not empty paragraph element
10.1.4 Output
Not empty paragraph text
Not empty paragraph element
10.2 Insert wrapping element
This recipe demonstrates the insertion of a wrapping element around multiple tags.
This recipe demonstrates adding a target attribute to any a (link) tags on a page. This recipe will also ensure that any children elements of the given a tag will be maintained (such as img tags, as shown) and that if said attribute is already set, its value will be maintained. Note that due to processing, the attribute’s ordering on the tag may change.
10.3.1 Rules
10.3. Adding an attribute to elements 41 Diazo Documentation, Release 1.0b1
Each recipe lives in a folder under docs/recipes and follows a standard format that facilitates automated testing, ensuring each recipe works as advertised.
