|
|
This document is used as a working draft for
Apache Cocoon architects to understand the issues associated with
sitemaps and XML publishing in general. It must be considered as a working
draft and may be updated at any time.
See the User documentation
for details about configuration of each sitemap component.
See the Example sitemap snippets.
Explore each sitemap.xmap in the distribution, to see
how the various situations are handled.
This document is based on ideas and design patterns inspired by Stefano
Mazzocchi (stefano@apache.org) and Pierpaolo Fumagalli (pier@apache.org)
but grew as a collaborative effort to provide a solid foundation of
design patterns and usability guidelines to create a solid foundation
of sitemap programmability and usability to the Cocoon Publishing
Framework.
This is one of the few examples where open source is transformed into
"open development" leading both the implementation and the pure research
around software development and usability.
|
The goal of the sitemap is to allow non-programmers to create web sites
and web applications built from logic components and XML documents.
It finds inspiration from both Apache's httpd.conf/.htaccess files as well
as from Servlet API 2.2 WAR archives. It uses concepts such as Cascading
from W3C CSS, as well as declarative approaches integrated into the W3C
XSLT language. It also uses some element/attribute equivalence patterns
used in W3C RDF.
The following goals were identified as engineering constraints:
- minimal verbosity is of maximum importance.
- the schema should be sufficiently expressive to allow learning by
examples.
- sitemap authoring should not require assistive tools, but be
sufficiently future-compatible to allow them.
- sitemaps must scale along with the site and should not impose growth
limitation to the site as a whole nor limit its administration with size
increase.
- sitemaps should contain all the information required to Cocoon to
generate all the requests it receives.
- sitemaps should contain information for both dynamic operation as
well as offline generation.
- uri mapping should be powerful enough to allow every possible mapping
need.
- basic web-serving functionalities (redirection, error pages,
resource authorisation) should be provided.
- sitemaps should not limit Cocoon's intrinsic modular extensibility.
- resources must be matched with all possible state variables, not
only with URI (http parameters, environment variables, server
parameters, time, etc...).
- sitemaps should embed the notion of "semantic resources" to be
future-compatible with semantic crawling and indexing.
- sitemaps should be flexible enough to allow a complete web site to
be built with Cocoon.
|
 |  |  |
 |
<map:components>
<map:generators/>
<map:transformers/>
<map:serializers/>
<map:readers/>
<map:selectors/>
<map:matchers/>
<map:actions/>
</map:components>
|  |
 |  |  |
|
|
Cocoon relies on the pipeline model: an XML document is pushed through a pipeline,
that exists in several transformation steps of your document.
Every pipeline begins with a generator, continues with zero or more transformers,
and ends with a serializer. Beside this normal processing each pipeline
may define its own error handling, too.
Beside using the various components, you can use matchers, and selectors to choose a
specific pipeline processing. Aggregation allows you to build a hierarchy of pipelines.
Using views allows you to define exit points in a pipeline.
|
Defining a pipeline is simple.
Just write a map:pipeline element inside the
map:pipelines element.
|
Having defined a pipeline you can use following sidemap elements:
Element
| Description
|
map:match
| Selects pipeline processing depending on matching
|
map:select, map:when, map:otherwise
| Selects pipeline processing depending on selecting
|
map:mount
| Mounts a sub sitemap
|
map:redirect-to
| Redirects to a another pipeline
|
map:parameter
| Defines additional parameters for the sitemap components
|
map:act
| Peform action processing
|
map:generate
| Defines the generation step
|
map:aggregate, map:part
| Defines an alternate generation step by mergine pipelines
|
map:transform
| Defines zero or more transformation steps
|
map:serialize
| Defines the final serialization step
|
map:handle-errors
| Handles processing errors
|
The usage of these sitemap elements is explained in the following sections in more detail.
|
These powerful sitemap components allow Cocoon to associate a pure "virtual" URI space
to a given set of instructions that describe how to generate,
transform and present the requested resource(s) to the client.
See also
Implementing Matchers And Selectors
|
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 .
See also
Implementing Matchers And Selectors
|
Apache Cocoon has a rich set of tools for publishing web documents,
and while XSP and Generators provide alot of functionality, they still mix content
and logic to a certain degree. The Action was created to fill that gap.
Because the Cocoon Sitemap provides a mechanism to select the pipeline at run time,
we surmised that sometimes we need to adjust the pipeline based on runtime parameters,
or even the contents of the Request parameter.
Without the use of Actions this would make the sitemap almost incomprehensible.
See also
Creating And Using Actions
|
A generator is the starting point of an xml pipeline.
It generates XML content as SAX events and initialize the pipeline processing.
See also
Generators in Cocoon.
|
A transformer is the central point in the pipeline.
It transform SAX events in SAX events.
See also
Transformers in Cocoon.
|
A serializer is the end point of an xml pipeline.
It transform SAX events in binary or char streams for final client consumption.
See also
Serializers in Cocoon.
|
Basically, views let you specify exit points of your pipelines
that are taken whenever a particular view is requested.
The processing continues with the definitions in the requested view.
The advantage over selectors that could achieve the same is, that these
exit points are not necessarily declared for each pipeline individually,
but once per sitemap.
|
|
In the sitemap, you can use all protocols nearly everywhere
(except for in map:redirect ).
Inside your components, you can also use these protocols whenever you
have a SourceResolver handy.
-
context://
- get a resource using the servlet context
-
cocoon:/
- get a pipeline from the current sitemap
-
cocoon://
- get a pipeline using the root sitemap
-
resource://
- get a resource from the context classloader
|
|
|