Goal
This document lists all available selectors of Apache Cocoon and
describes their purpose.
See also the concepts document
Using and Implementing
Matchers and Selectors.
Overview
Selectors in Apache Cocoon have a role similar to matchers
while being more flexible. Like matchers they are designed
to test something against a part of the environment (the
request URI, headers, cookies and so on), but unlike matchers
they can be active decision driving components.
A matcher allows only for simple
"yes/no" decisions: the match can be succesful or not, if it
is the pipeline is executed, if not it's simply ignored.
Selectors go a step further allowing for more complex
use cases, where there is need for a decision to be
made according to a multiple chance scenario. In short you can
think of matchers as an "if" statement, while selectors have all
the power of an "if-else if-else" or "switch-case" construct.
The selector syntax is similar will be familiar to people
using the XSLT <xsl:test> statement.
As an example consider the typical scenario where a page has to
be rendered in different way according to the browser being
used. There are plenty of browsers out there so expressing this
need as a set of matchers might become ankward and counterintuitive.
Using the BrowserSelector, which checks a given pattern
against the user-agent header, it's easy to deploy a consistent
and readable setup:
 |  |  |
 |
<map:match pattern="docs/*.html">
<map:generate src="xdocs/{1}.xml"/>
<map:select type="browser">
<map:when test="netscape">
<map:transform src="stylesheets/netscape.xsl" />
</map:when>
<map:when test="explorer">
<map:transform src="stylesheets/ie.xsl" />
</map:when>
<map:when test="lynx">
<map:transform src="stylesheets/text-based.xsl" />
</map:when>
<map:otherwise>
<map:transform src="stylesheets/html.xsl" />
</map:otherwise>
</map:select>
<map:serialize/>
</map:match>
|  |
 |  |  |
The Selectors in Cocoon
These are the available Selectors in Cocoon:
-
BrowserSelector: matches the value of the "test"
parameter against the HTTP User-Agent header, allowing to
recognize the browser being used;
-
CodeSelector: matches a snippet of Java code
given as the "test" parameter against the environment;
-
HostSelector: matches the "test" parameter value
against the Host request header
-
ParameterSelector: matches the string specified
in the "test" parameter against a specified Cocoon internal
(e.g. sitemap) parameter;
-
HeaderSelector: same as the Parameter selector,
but matches against the request headers;
-
RequestSelector: again, same as the Parameter selector,
but matches against the Request parameters;
-
SessionSelector: finally, this selector is used as
the Parameter selector to match against an arbitrary session
attribute;
|