On 14.06.2008 09:06, Kamal wrote:
Something I have noticed about the Cocoon documentation is that the
terms "pipeline" seems to be used to describe a map:match. For example:
"Sets the generator for the pipeline."[1]
We know what is meant, but this could be very confusing for a newbie.
Should we be using the term "match" here, perhaps with a link the
description of map:match? I know historically, it is a pipeline.
Cheers.
PS. I have been adding the clearer descriptions to the various sitemap
component found in the Cocoon 2.1 documentation. Are there any objections?
Yes, because it's wrong. It is a pipeline, not a match. A match is just
similar to an if and has nothing to do with a pipeline as you can see in
the following example:
<map:pipeline>
<map:match>
<map:generate/>
<map:transform/>
<map:match>
<!-- executes 2nd transform only in certain cases -->
<map:transform/>
</map:match>
<map:serialize/>
</map:match>
</map:pipeline>
or
<map:pipeline internal-only="true">
<map:match>
<map:generate/>
<map:transform/>
</map:match>
<map:match>
<map:generate/>
</map:match>
<!-- ALL internal pipeline use XML serializer -->
<map:serialize type="xml"/>
</map:pipeline>
The confusion result from 2 facts: In most cases one complete pipeline
is wrapped within one map:match statement. There is no obvious wrapping
for the actual pipeline, map:pipeline seems to wrap multiple pipelines
rather than one. But that's not quite true if you read it differently: A
pipeline starts with the first generator that the treeprocessor comes
along the path and ends with the first serializer. A map:match (just
like an if) excludes a map:generate from certain paths to be found.
Other examples:
<map:pipeline>
<map:generate/>
<map:transform/>
<map:serialize/>
<map:match>
<!-- will never be reached -->
</map:match>
</map:pipeline>
The first combination of map:generate to map:serialize make the
pipeline, map:match will never be reached.
<map:pipeline>
<!-- different generator for different paths -->
<map:match pattern="path1">
<map:generate/>
</map:match>
<map:match pattern="path2">
<map:generate/>
</map:match>
<!-- same transformation -->
<map:transform/>
<map:match pattern="path1">
<map:serialize/>
</map:match>
<!-- "path1" won't reach this, only "path2" -->
<map:serialize/>
</map:pipeline>
So technically map:pipeline IS the wrapper for a complete pipeline,
because always only one pipeline will be constructed within it. It's
just not that obvious.
Disclaimer: The above examples should all work in Cocoon, but that does
not mean I recommend to use them. The standard case of wrapping a
pipeline within a map:match probably makes a sitemap more readable and
useful than these examples to outline the concepts.
Joerg
