Using EP With XDV Themes
Using EP With XDV Themes
This section gives background about XDV themes and different ways to implement them with Plone + Enfold Proxy. It assumes that you are comfortable with configuring proxy definitions by editing the eep.ini file rather than using the EP configuration tool. (See also: list of common EP fields in this eep.ini file for reference). It covers some advanced topics likely to be of interest to developers only. If you interested in a simple setup of XDV themes, read the XDV Tutorial. Some of this information on this page comes from the original XDV documentation.
First, you will need to declare your xdv in a separate xdv section of your ep.ini file. Then you will need to configure your hosts in the eep.ini file so that they can "see" the different xdv themes. This topic will cover many ways to configure your xdv section. The last step (discussed near the end of this topic) is to add a reference to the configured themes in the host section of your eep.ini file.
Selecting a theme based on URLs
We have the site http://host/ and we need to define xdv theme so that they are used like this.
http://host/ - gets theme1/rules1 (default theme)
http://host/news - gets theme2/rules2
http://host/path/to/content.html - gets theme3/rules3
http://host/path/to2/ - gets theme3/rules3
For each theme we should define a separate [xdv ...] section in eep.ini .
Let's define default themes:
[xdv default] rules=path_to_rules1\rules.xml theme=path_to_theme1\theme.xml
Now the theme for the news directory. It uses the 'url' field to define to which url this theme applies.
[xdv news] rules=path_to_rules2\rules.xml theme=path_to_theme2\theme.xml url=/news
Now theme 2, we can define any number of url to apply theme
[xdv theme3] rules=path_to_rules3\rules.xml theme=path_to_theme3\theme.xml url=/path/to/content.html ^/path/to2
Each url definition is a regular expression.
Now we have to define one or more XDV themes for the section of eep.ini which declares the proxy definition.
[host robert-proxy-definition-name] vh_hosts= *whatever value is appropriate*; xlst_enabled = True themes = news theme3 default
themes - list of theme names.
Order does matter because EP will use the first XDV theme it matches.
Selecting a theme based on URLs & HTTP Headers
Here is a more complex example of how EP can process rules to decide which theme to send back.
EP automatically compiles xdv themes and recompiles them whenever rules or theme file have changed. You can apply different xdv themes to different urls. Which theme is returned depends on whether the rules for the theme have been met. This general example below shows how you can apply a theme for a URL depending on what header EP receives.
There are various reasons why you would want to serve a theme depending on the HTTP header. One use case would be serving a different theme depending on whether the site visitor is an authenticated user or not.
EP xdv theme definition:
[xdv theme_name] rules=path_to_rules theme=path_to_themes absolute_prefix = url absolute prefix reload = true url= URL_regex1 URL_regex2 URL_regex3 headers= HEADER_NAME1|regexp1 HEADER_NAME2|regexp2 HEADER_NAME3|regexp3
rules = path to xdv 'rules.xml' file
theme = path to xdv 'theme.html' file
reload = check if for modifications in rules and theme files in each request if these files are modified
url. apply theme to this urls, url is regex. Apply theme if any url is matched; optional, Empty url means "apply to all urls".
headers = list of (header name, header value regexp). Apply theme if all headers match. Optional. Empty headers mean "apply to all URLs."
absolute_prefix = The compiler can be passed an "absolute prefix". This is a string that will be prefixed to any relative URL for 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 viewed standalone on the filesystem, even if at runtime its static resources are going to be served from some other location.
Headers are keys in environment dictionary. The environment dictionary logs to proxy.log in debug log level. (See below).
Selecting a theme by not meeting a certain rule
It is also possible to select themes based on not meeting a rule. Let's look at that same example (slightly modified).
[xdv theme_name] rules=path_to_rules theme=path_to_themes absolute_prefix= reload = true url= URL_regex1 URL_regex2 !URL_regex3 headers= HEADER_NAME1|regexp1 HEADER_NAME2|regexp2 !HEADER_NAME3|regexp3
Here, the rules and theme options represent the paths to the XDV rules.xml and theme.xml files. The reload option must be set to either true or false. If reload is set to true, then on each request, Enfold Proxy checks for modifications to rules.xml and theme.xml and recompiles those files if necessary.
The url option is a list of regular expressions. Enfold Proxy applies the XDV theme to any URL that matches any regular expression in this list. An empty list means to apply the XDV theme to all requests, regardless of URLs. You can use ! char before each url, this means NOT MATCH or apply theme to any url except this.
The headers option is a list of name and regular expression pairs. Enfold Proxy applies the XDV theme if all of the headers match their specified regular expressions. An empty list means to apply the XDV theme to all requests, regardless of header values. You can use ! char before each header name, this means NOT MATCH or apply theme except if header doesn't match specifies regular expression. The request headers are represented as a key in the environment dictionary which is logged in the proxy.log file at the debug log level.
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.
The Last Step: Adding the theme(s) to a proxy definition
Enfold Proxy supports associating several themes with hosts. The configuration in eep.ini looks like this:
[host ...] themes=theme_name_1 theme_name_2
Here, themes represents a list of XDV themes. Note that the order matters - for each request. Enfold Proxy applies the first theme that matches the request's URL and headers (detailed above).
Setting up a XSLT Logger in EP to debug XSLT
In the XDV Tutorial, we talked about a simple way to set up logs when debugging XDV themes. This is verbose logging (and don't forget to turn it off!)
[xslt] level = DEBUG
However, after the xdv themes have been configured to work with EP, you will want to change this to a less verbose log which is geared towards tracking unusual events:
[xslt] filename=logs/xslt.log level=WARN eventlog_level=CRITICAL max_size=500000 backup_count=4
XDV and HTTP Status Codes
If XDV is enabled for a site, it themes all responses from a back-end host with the text/html, text/xml, and application/xhtml+xml Content-Types and 200, 404, 500, and 503 status codes. XDV does not theme any response with any other content type or status code. Further, if Enfold Proxy is configured to serve custom 40x and 50x status pages, XDV does not theme these responses.