Sitemap Guide

The sitemap is the key part of running a site based on either Cocoon and Paloose. It defines all the components to be used and the pipelines to be run in response to a particular browser request. It is definitely worth reading the Apache documentation about the Cocoon sitemap.

Note
Remember that everything that goes through Paloose takes time. Rather than use Paloose to serve files see if Apache can do this for you. In general resources such as style sheets and images are static files and do not need transforming. This is the same situation in Cocoon: if Apache can serve it — don't process it.

The Structure

The Paloose site has a similar structure to the Cocoon one, just less of it.

<?xml version="1.0"?> <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"> <map:components> <map:generators/> <map:transformers/> <map:serializers/> <map:selectors/> <map:readers/> <map:matchers/> </map:components> <map:views/> <map:resources/> <map:pipelines/> </map:sitemap>

Sitemap Namespace

The Paloose namespace is identical to that used by Cocoon (http://apache.org/cocoon/sitemap/1.0), though there is no real reason why it should not be one specific to Paloose. This could be changed in future. If you wish to do this yourself note that the namespace is changed in the main Paloose configuration file in the user's site.

Components

The Paloose sitemap components are described elsewhere. However there are some common concepts that are described below.

Regular Expression Pattern Matching

Since version 0.7.0 it has been possible to carry out matching using regular expressions. Paloose regular expressions are not the same as Cocoon regular expressions. The PHP5 version based on Perl is used and a full description of the regexp can be found on the PHP5 manual page. The pattern variables work in similar fashion as the wildcard matcher. For example:

<map:match type="regexp" pattern="/.*\.(html)|(tex)|(xml)/"> ... </map:match>

would match all requests that have a file extension "html", "tex" and "xml". In the following all requests for documents between "nb1996" and "nb1999" would read the html file directly:

<map:match type="regexp" pattern="/nb199([6789]).html/"> <map:read src="context://nb/199{1}/nb199{1}.html"/> </map:match>

and the following would take all others in 2000 or later and process them from an XML file.

<map:match type="regexp" pattern="/nb20(.+).html/"> <map:generate src="cocoon:/20{1}/nb20{1}.xml" label="xml-content"/> <map:transform src="context://resources/transforms/notebooks-html.xsl" label="page-transform"> <map:parameter name="page" value="nb20{1}"/> </map:transform> <map:serialize/> </map:match>

Variables

There are variables that can be used within the sitemap. These are stored in the appropriate module and can be accessed by using the syntax "{module_name:variable_name}". There are currently two preset modules for variables: global, error and request-param.

Global Variables

Global variables can be declared within each sitemap and are available to each subsitemap. They are also overwritten by subsitemap declarations. They are declared within the sitemap pipelines declaration as a component configuration element, for example

<map:pipelines> <map:component-configurations> <global-variables> <composer>Bach</composer> </global-variables> </map:component-configurations> ...

which would set the global variable "composer" to the string "Bach". It could then be accessed like other variables within the sitemap as:

<map:transform type="mysql" label="sql-transform"> <map:parameter name="show-nr-of-rows" value="true"/> <map:parameter name="composer" value="{global:composer}"/> </map:transform>

Note that since Version 1.3.4 the sitemap variables formed from the matcher "{0},{1},{2},..." have been included in the global variables. The can be accessed by using "{global:__0},{global:__1},{global:__2},..." respectively.

Request Parameter Variables

One important set The RequestParameterModule allows access to the query string variables. For example if the URI request is index.html?locale=en the RequestParameterModule gives the sitemap access to the query string. Using this is very simple

<map:match pattern="**.html"> <map:generate src="context://{1}.xml"/> <map:transform src="context://resources/transforms/page2html.xsl"> <map:parameter name="locale" value="{request-param:locale}"/> </map:transform> ... </map:match>

This would pass the parameter locale into the XSLT script where it could be accessed using the following typical code:

<xsl:param name="locale"/> ... <xsl:value-of select="$locale" />

Handling Pipeline Errors

When an error is detected in a sitemap (page does not exist because a matcher has not fired, for example) a specialised error pipeline is run. More details can be found in the Handle Error documentation page.

Protocols

As in a Cocoon sitemap, you can use all protocols nearly everywhere in a Paloose sitemap. The following are a list of the Paloose protocols and what they mean. Note that there are subtle differences to Cocoon.

Copyright 2006 – 2017 Hugh Field-Richards. All Rights Reserved.