repoze.dvselect Documentation

Overview

repoze.dvselect provides a WSGI middleware component which reads assertions set by repoze.urispace into the WSGI environment, and uses them to select themes and rules for Deliverance based on the URI of the request.

Because it reads the assertions created by the repoze.urispace middleware, the repoze.dvselect middleware must be configured “downstream” from the repoze.urispace middleware (i.e., nearer to the application); otherwise there will be no assertions to use.

Because it tweaks the WSGI environment, the repoze.dvselect middleware must be configured “upstream” from the Deliverance middleware / proxy (i.e., nearer to the server); otherwise Deliverance will have already selected the theme / rules to use.

Example: Using different theme / rules for sections of a site

This example assumes that the site being themed is something like a newspaper site, where different “sections” have different layouts.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
<?xml version="1.0" ?>
<themeselect
   xmlns:uri='http://www.w3.org/2000/urispace'
   xmlns:uriext='http://repoze.org/repoze.urispace/extensions'
   >

 <!-- default theme and rules -->
 <theme>http://static.examples.com/themes/default.html</theme>
 <rules>http://static.examples.com/rules/default.xml</rules>

 <uri:path uri:match="news">
  <theme>http://static.examples.com/themes/news.html</theme>
  <uri:path uri:match="world">
   <theme>http://static.examples.com/themes/news.html?style=world</theme>
  </uri:path>
  <uri:path uri:match="national">
   <theme>http://static.examples.com/themes/news.html?style=national</theme>
  </uri:path>
  <uri:path uri:match="local">
   <theme>http://static.examples.com/themes/news.html?style=local</theme>
  </uri:path>
 </uri:path>

 <uri:path uri:match="lifestyle">
  <theme>http://static.examples.com/themes/lifestyle.html</theme>
 </uri:path>

 <uri:path uri:match="sports">
  <theme>http://static.examples.com/themes/sports.html</theme>
 </uri:path>

 <!-- Note that the following rules match "across" sections -->
 <uriext:pathlast uri:match="*.html">
  <rules>http://static.examples.com/rules/story.xml</rules>
 </uriext:pathlast>

 <uriext:pathlast uri:match="index.html">
  <rules>http://static.examples.com/rules/index.xml</rules>
 </uriext:pathlast>

</themeselect>

The purpose of this file is to compute two values (called “assertions” by the URISpace spec) based on the request URI:

  • the theme assertion is the URI to be used by Deliverance as the theme for this request. It should be a URI for a static HTML page. This example assumes that the theme pages are served from a separate server than the main application; see the Deliverance docs for details about serving the theme from within the main application.
  • the rules assertion is the URI to be used by Deliverance as the rules mapping the content onto the theme for this request. It should be a URI for an XML document. This example assumes that the rules are served from a separate server than the main application; see the Deliverance docs for details about serving the theme from within the main application.

Prolog

  • Line 1 is the stock XML prolog.
  • Lines 2 - 5 define the root element (its element name is irrelevant to URISpace) and the namespaces used in the document.
  • The uri: namespace defined in line 3 is the stock namespace for URISpace.
  • The uriext: namespace in line 4 is used for extensions defined by repoze.urispce: this document uses the uriext:pathlast extension element.

For details of the syntax of this file, please see the repoze.urispace docs.

Default Assertions

Liens 9 and 10 define the default theme and rule assertions: they will be used if no other rule matches the request URI.

Assertions for Sections

  • Lines 11 - 22 are conditioned by a match on news as the first element of the path in the URI.
  • Line 12 overrides the theme for requests in the news section.
  • Lines 13 - 15 override the theme further, for items which are in the news/world subsection. Likewise, lines 16 - 18 override it for the news/national subsection, and lines 19 - 21 for the news/local subsection.
  • Lines 24 - 26 are conditioned by a match on lifestye as the first element of the URI path; they override the theme accordingly.
  • Lines 28 - 30 are conditioned by a match on sports as the first element of the URI path; they override the theme accordingly.

Note that none of these URISpace assertions override the rules assertion, which means that the default assertion applies.

Assertions for Pages

  • Lines 33 - 35 match URIs whose last path element matches the glob, *.html: they override the rules assertion, likely because the layout of the content resource is substantially different for stories.
  • Lines 37 - 39 re-override the rules assertion for the pages whose last path element is index.html (the “section front”).

Note that these last two matches vary the rules assertion independently from the theme assertion, which will have been set by the earlier, section-based matches.

Configuring repoze.dvselect via Paste

To configure the middleware via a Paste config file, you can just add it as a filter to the WSGI pipeline: it doesn’t require any separate configuration.

You also need to configure the repoze.urispace middleware as a filter, supplying the filename of the XML file defining the URISpace rules. E.g., assuming we put the URISpace configuration from the example above into the same directory as our Paste config file, and call it urispace.xml, the filter configuration would be:

[filter:urispace]
use = egg:repoze.urispace#urispace
urispace = %(here)/urispace.xml

Assuming that our Paste configuration defines a setup where the Deliverance proxy is the application, we would configure it as:

[app:deliverance]
use = egg:Deliverance#proxy
wrap_ref = http://example.com/
theme_uri = http://static.example.com/themes/default.html
rule_uri = http://static.example.com/rules/default.xml

We would then set up the pipline with the repoze.urispace filter first in line, followed byt eh repoze.dvselect filter, followed by the proxy:

[pipeline:main]
pipeline =
  urispace
  egg:repoze.urispace#urispace
  deliverance

Configuring repoze.dvselect via Python

Defining the same middleware via impertive python code would look something like the following:

from deliverance.proxyapp import ProxyDeliveranceApp
from repoze.dvselect import DeliveranceSelect
from repoze.urispace.middleware import URISpaceMiddleware

proxy = ProxyDeliveranceApp(
         theme_uri = 'http://static.example.com/themes/default.html',
         rule_uri = 'http://static.example.com/rules/default.xml',
         proxy = 'http://example.com/',
        )
dvselect = DeliveranceSelect(proxy)
urispace = URISpaceMiddleware(dvselect, 'file://etc/urispace.xml')

application = urispace

This example builds the WSGI pipeline by composing the application and the filters together via their constructors.