cocoon-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Joerg Heinicke <joerg.heini...@gmx.de>
Subject Re: pipeline vs match
Date Sat, 14 Jun 2008 17:23:40 GMT
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

Mime
View raw message