apache > cocoon

- Home

# XInclude Transformer

This transformer works according to the XInclude specification.

For more information refer to the XInclude specification.

- Name : xinclude
- Class: org.apache.cocoon.transformation.XIncludeTransformer
- Cacheable: yes.

You can include either simple text, or xml content. Including xml content -- which is the default -- gives you the option to define an xpointer in the href attribute. Some quick xinclude examples should reveal the possibilities of xinclude.

- Include an xml content as-is: `<xi:include href="include.xml"/>`
- Include an xml content but pick the strong element only: `<xi:include href="include.xml#xpointer(/p/strong)"/>`
- Include text content: `<xi:include parse="text" href="include.txt"/>`

A simple example using xinclude might help to use this transfomer effectively:

Add the XIncludetransfomer to the components in your sitemap.xmap

    ...
    <map:components>
    ...
      <map:transformers default="xslt">
      ...
        <map:transformer name="xinclude"
          src="org.apache.cocoon.transformation.XIncludeTransformer"/>
      ...

Next define in your pipeline to use the XIncludeTransformer

    <map:match pattern="xinc/simple-xinc">
      <map:generate src="xinc/simple-xinc.xml"/>
      <map:transform type="xinclude"/>
      <map:transform src="stylesheets/page/simple-page2html.xsl"/>
      <map:serialize/>
    </map:match>

In this example pipeline it assumed that simple-xinc.xml contains the include element. As well as defining the include element, it defines the namespace URI "http://www.w3.org/2001/XInclude". This helps the XIncludeTransformer to find the include element to get replaced by the included content. The simple-xinc.xml may look like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <page
      xmlns:xi="http://www.w3.org/2001/XInclude">
      <title>Hello</title>
      <content>
        <para>This is my first Cocoon page!</para>
        <xi:include href="include.xml"/>
      </content>
    </page>

Next you should define the include.xml file which is included. A simple include.xml might look like this:

    <?xml version="1.0"?>
    <p>
      I am <strong>included</strong> by XIncludeTransformer.
      I come from "include.xml".
    </p>

Now finally we have everything put together the xml content after the XIncludeTransformer processing will look like this:

    <?xml version="1.0" encoding="UTF-8"?>
    <page
      xmlns:xi="http://www.w3.org/2001/XInclude">
      <title>Hello</title>
      <content>
        <para>This is my first Cocoon page!</para>
          <p>
           I am <strong>included</strong> by XIncludeTransformer.
           I come from "include.xml".
          </p>
      </content>
    </page>

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).