Copyright 1999-2004 The Apache Software Foundation
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.
-->
<!DOCTYPE faqs PUBLIC "-//APACHE//DTD FAQ V1.0//EN" "faq-v10.dtd">
<faqs title="Cocoon Sitemap Transformer FAQs">
<faq>
<question>
What is a transformer?
</question>
<answer>
<p>
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.
</p>
<p>
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.
</p>
<p>
For more conceptual information about transformers see <link href="../userdocs/concepts/sitemap.html">the sitemap</link>. For detailed descriptions about all of the available Cocoon transformers, see the user's guide document <link href="../userdocs/transformers/transformers.html">Transformers in Cocoon</link>. You may also wish to consult the Cocoon API documentation.
</p>
</answer>
</faq>
<faq>
<question>
What are the similarities and differences of XInclude and CInclude Transformers?
</question>
<answer>
<p>
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).
</p>
<p>
XIncludeTransformer differences
</p>
<ul>
<li>Implements the W3C XInclude specification.</li>
<li>Allows you to include text or xml content (via parse="text|xml").</li>
<li>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.</li>
<li>Has only one implementation, XIncludeTransformer, which is <strong>not</strong> cacheable.</li>
</ul>
<p>
CIncludeTransformer differences
</p>
<ul>
<li>Helps you serve documents with inclusions and tags in xinclude namespace.
This means that if a document (with both xinclude <em>and</em> cinclude tags) is processed
by the CIncludeTransformer, its xinclude tags will remain intact.</li>
<li>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")</li>
<li>Has two implementations: (1) a cacheable implementation, CachingCIncludeTransformer, and (2) a non-cacheable implementation, CIncludeTransformer, (used in Cocoon samples).</li>
</ul>
<p>
Consult the user documentation for more information about the <link href="../userdocs/transformers/xinclude-transformer.html">XIncludeTransformer</link> and <link href="../userdocs/transformers/cinclude-transformer.html">CIncludeTransformer</link>. Please note that an IncludeTransformer, with support for both cinclude and xinclude as well as a configurable namespace, is planned for a future release.
