Cocoon Sitemap Transformer FAQs

What is a transformer?

A transformer is the central point in a sitemap pipeline. Within a pipeline match, transformers consume SAX events and emit SAX events. Transformers are placed inside a pipeline matcher between a generator and a serializer. You can include several transformers within a pipeline matcher. Any pipeline matcher containing a generator and transformer must end with a serializer.

In the sitemap file, each transformer has a unique name which is mapped to a java class. One transformer name must be declared as the default transformer. Each transformer may have additional configuration information specified in child elements.

For more conceptual information about transformers see the sitemap. For detailed descriptions about all of the available Cocoon transformers, see the user's guide document Transformers in Cocoon. You may also wish to consult the Cocoon API documentation.

What are the similarities and differences of XInclude and CInclude Transformers?

The XInclude and CInclude transformers both provide mechanisms to include content from other documents. Both also support cocoon:/ protocol (i.e. they use Cocoon's resolver).

XIncludeTransformer differences

• Implements the W3C XInclude specification.
• Allows you to include text or xml content (via parse="text|xml").
• Allows you to use XPointer syntax (via '#' or XPointer() syntax) within href attribute. However, support of XPointer requires random access to the object model of XML document to be included. Thus, it is expensive to construct in runtime. If you are including a whole document, it's better to use CInclude which supports straightforward text inclusion.
• Has only one implementation, XIncludeTransformer, which is not cacheable.

CIncludeTransformer differences

• Helps you serve documents with inclusions and tags in xinclude namespace. This means that if a document (with both xinclude and cinclude tags) is processed by the CIncludeTransformer, its xinclude tags will remain intact.
• Gives you the option to specify the element, namespace, and prefix for the included content (e.g. element="wrapper_element" ns="wrapper_ns" prefix="wrapper_prefix")
• Has two implementations: (1) a cacheable implementation, CachingCIncludeTransformer, and (2) a non-cacheable implementation, CIncludeTransformer, (used in Cocoon samples).

Consult the user documentation for more information about the XIncludeTransformer and CIncludeTransformer. Please note that an IncludeTransformer, with support for both cinclude and xinclude as well as a configurable namespace, is planned for a future release.