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.

The Structure

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

Sitemap Namespace

The 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.

Common Attributes of Components

Like Cocoon all components have some common attributes.

• name — Gives the component an identifying name by which it may be referenced in the pipeline section.
• src — Specifies the PHP file to be used implementing this component. This is a major change to Cocoon where the class is used not the file name.

Component Parameters

Some component declaration use parameters to allow user-settable values to be incorporated in the definition, for example see the PageHitTransformer.

Subsitemap Component Definitions

Components can be defined with a subsitemap overriding a declaration made in a higher sitemap. The new definition is available to all sitemaps called by the one where the declaration is made.

Generators

A Generator generates XML content as DOM objects and initializes the pipeline processing. Using DOM instead of SAX is a change from Cocoon (see this FAQ). For example defining the FileGenerator generator:

The default attribute specifies the type of generator to use if none is specified in a pipeline. Further discussion on the types of generator are on the Generators Page.

Transformers

Transformers change a DOM into a another DOM using either an XSLT file or a custom translator. For example this defines TRAXTransformer which performs standard XSLT transformations, similar to Cocoon.

The default attribute specifies the type of transformer to use if none is specified in a pipeline. Further discussion on the types of generator are on the Transformers page.

Serializers

Serializers change a DOM into a stream of characters that the client can use. There are several serializers that work in a similar fashion to Cocoon, although not so extensive: only encoding and doctype in the XHTML/HTML serializers is currently supported. For example

See the Serializers page for more information.

Readers

Readers are used to deliver resources directly from the server to the client, usually without modification. As such they are generator, transformer and serializer all in one. In Paloose there is currently only one type of matcher: ReasourceReader, which is equivalent to the Cocoon reader of the same name.

The default attribute specifies the type of reader to use if none is specified in a pipeline.

Selectors

Selectors allow conditional processing within the pipeline. Currently the only selector supported by Paloose if the BrowserSelector which allows different routes through a pipeline to be taken dependent on the client's browser.

See the Selectors page for more information.

Aggregators

Aggregators takes several XML documents and combine them into a single DOM, with appropriate enclosing tags for each part. They are equivalent to generators and thus must be placed first in a pipeline. See Aggregators page for more information.

Matchers

Matchers are used to match the request into a particular pipeline. In Paloose (version 0.7.0 or later) there are two types of matcher: WildcardURIMatcher and RegexpURIMatcher. WildcardURIMatcher is equivalent to the Cocoon matcher of the same name. However RegexpURIMatcher is slightly different to its Cocoon equivalent: it uses a PHP-modified Perl regular expression syntax. For details of this see the PHP5 manual pages)

The default attribute specifies the type of matcher to use if none is specified in a pipeline.

Views

Views are means of interrupting the normal pipeline flow under the control of the user via the quesry string. It is similar to that of Cocoon but not quite so extensive. It is a useful debugging aid. See the Views documentation page for more information.

Pipelines

Like Cocoon the heart of Paloose is the sitemap pipeline. Documents are entered one end of the pipeline (via a generator), progress through pipeline via zero or more transformations (transformers) and end up being processed to the client (via a serializer). Paloose also support aggregation to build up a document from a variety of other documents (or pipelines).

Paloose also supports a similar error handling procedure to Cocoon, although there are some slight differences withn the handlers.

Defining a Pipeline

Pipelines are defined within the map:pipelines element within individual map:pipeline elements.

An individual pipeline can be marked as " internal only" so that itis impossible to activate it from an external URL request. This is generally done on aggregation to hide the intermediate parts from direct access. It is declared

Pipeline Elements

Paloose supports a subset of the Cocoon sitemap pipeline elements:

• map:match — Selects which pipeline to run dependant on the incoming request.
• map:mount — Transfers control to a sub-site map for further processing.
• map:parameter — Defines a parameter to be carried into one of the pipeline elements.
• map:generate — Defines the generation step.
• map:aggregate, map:part — Combines several XML files into a single document.
• map:transform — Defines the transformation step.
• map:serialize — Defines the serialization step.
• map:select — Select which pipeline fragment to run.
• map:act — Perform some interaction with external resource.
• map:redirect-to — Redirect this URL request to another URL.
• map:handle-errors — Handles processing errors.

Internal Pipelines

Sometimes it is desirable to mark a pipeline to be only accessable from the sitemap itself. This is of particular use when aggregation is used (and authorisation). It prevents scraps of documents which are used in assembling a complete document from being accessed. See the documentation on aggregation for an example of how this is used.

The general structure is:

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

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

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.

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.

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.

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:

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

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

Variables

There are other variables that can be used within the sitemap. 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

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

Note the format of the variable, it is formed of a pair "{module name:variable name}". As other predefined modules are added the module name will be used to access the variables defined by the module.

Global Variables

Global variables can be declared within each sitemamp 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

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

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.

Handling Pipeline Errors

When an error is detacted 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 directory where user's site is installed
• cocoon:/ — get a resource from the current sitemap directory
• cocoon:// — get a resource using the root sitemap directory
• resource:// — get a resource from directory where Paloose is installed