• Documentation >
• Components

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:

• Generators form the start of a pipeline inject the XML into the pipeline as a DOM. There should always be one (but see aggregation, mount and read).

• Transformers take the pipeline data as a DOM document, transform it into another DOM and output back into the pipeline. There can be more than one transformer.

• Serializers take the pipeline data as a DOM document and output it to the client (a browser request or even an internal sitemap request).

• Aggregators takes several XML documents and aggregates them into a single XML document with appropriate enclosing tags for each part.

• Matchers are used to match the request into a particular pipeline.

• Selectors provide a simple conditional mechanism for the pipeline. It can be based on the type of browser being used or a switch/case statement.

• Actions provide the necessary hooks for interaction with the user. For example sending mail and user authentication.

• Views provide a means of interrupting the pipeline flow using a user defined query string. Useful to see the state of the pipeline at any point.

• Flows (forms etc) provide a mechanism for client forms and controlling the entry of user data.

• Style File Compiling provides support for the SASS/SCSS style file extension language.

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.

• 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. Parameters are held in the "params" module and can be access from with the sitemap as "{params:variable_name}".

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.

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

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

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:matchers — Matching URL against predefined pattern expression.
• 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 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: