Sitemap Components

Each sitemap consists of a series of pipelines that enclose a set of components in exactly the same form as Cocoon. These components provide the basic mechanism of reading (generating), transforming and outputting (serializing) data. The basic "language" of the data is XML, although some of the generating components are responsible for reading other types of data (for example GEDCOM) and producing an XML form of the data. The general flow of data through the sitemap is a series of transformers fed by a generator and outputting via a serializer:

Each pipeline is selected using a matcher that takes the URL and matches against a predefined string:

If a match is made then that pipeline is run by invoking the generator which in turn passes the generated XML to the transformer(s), eventually being output by the serializer.

Component Types

The components are main build bricks of the sitemap. They are explained in detail in the appropriate section:

However there are some common features to all components that are explained below.

Common Attributes of Components

Like Cocoon all components have some common attributes.

Component Parameters

Some component declaration use parameters to allow user-settable values to be incorporated in the definition, for example see the PageHitTransformer. Parameters are held in the "params" module and can be access from with the sitemap as "{params:variable_name}".

Subsitemap Component Definitions

Warning
Versions before 0.14.1: Component definitions in subsitemaps are handled differently to Cocoon. In the latter it is possible to redefine or declare a new component. In Paloose all declarations should be placed in the root sitemap, with just the default changed in the subsitemap.

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.

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)

<map:matchers default="wildcard"> <map:matcher name="wildcard" src="resource://lib/matching/WildcardURIMatcher"/> <map:matcher name="regexp" src="resource://lib/matching/RegexpURIMatcher"/> </map:matchers>

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 query 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 within the handlers.

Defining a Pipeline

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

<map:pipelines> <map:pipeline> <!-- pipeline elements --> </map:pipeline> <map:handle-errors> ... </map:handle-errors> </map:pipelines>

An individual pipeline can be marked as " internal only" so that it is 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

<map:pipelines> <map:pipeline internal-only="true"> <!-- pipeline elements --> </map:pipeline> </map:pipelines>

Pipeline Elements

Paloose supports a subset of the Cocoon sitemap pipeline elements:

Internal Pipelines

Sometimes it is desirable to mark a pipeline to be only accessible 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:

<map:pipelines> <map:pipeline> <!-- matchers appearing here are available externally and internally --> </map:pipeline> <map:pipeline internal-only="true"> <!-- matchers appearing here are available internally --> </map:pipeline> </map:pipelines>
Copyright 2006 – 2023 Hugh Field-Richards. All Rights Reserved.