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.

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

Warning

Note that this is a change from all versions prior to 1.13.0.

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> <variable name="composer" value="Bach"/> </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" />

Sitemap Variables and Matching Patterns

It is possible to define variables in the Cocoon sitemap. Paloose uses this principle, but, at present, uses a very restricted set. Like Cocoon variables are defined by enclosing them in brackets "{...}". The primary area where this is used is in the pattern matching.

Wildcard Pattern Matching

For example take the wildcard matcher

<map:match pattern="*/*.html"> ... </map:match>

The wildcards in the match pattern are assigned to internal pattern variables "{1}", "{2}" etc, in a similar fashion to Perl regular expressions. So in the above case if the pattern to be matched is "documentation/index.html" then there would be a match. The internal variables would be set {1} = "documentation" and {2} = "index". These variables are used within the various pipeline components to resolve string expressions. For example

<map:match pattern="*/*.html"> <map:generate src="context://{1}/{2}.xml"/> ... </map:match>

In this case the generator would fetch the file documentation/index.xml from the current application context (see pseudo protocols below). Note that the constructions "**" and "*" are different and are identical to their Cocoon counterparts.

"*" — Match any character except the path separator.
"**" — Match any character including the path separator.

The values for the pattern variables are taken from the current matcher. If you want to access a higher matcher (wherever it is) then you would have to use the string {../1}, which means access the pattern variable {1} in the previous matcher. These can be extended as necessary, for example {../../1} to access a matcher two levels above the current one.

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.

context:// — get a resource from directory where user's site is installed
cocoon:/ — get a resource from the current sitemap
cocoon:// — get a resource using the root sitemap

resource:// — get a resource from directory where Paloose is installed