CInclude Transformer

This transformer includes XML in the current stream and acts therefore is a kind of (dynamic) content aggregation. Two forms, one verbose and flexible approach, and a simple approach are supported by the transformer. We will first discuss the simple approach and the more flexible is mentioned in the next chapter.

This transformer triggers for the element include in the namespace "http://apache.org/cocoon/include/1.0". The src attribute contains the url which points to an xml resource which is included instead of the element. With the attributes element, ns and prefix it is possible to specify an element which surrounds the included content.


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

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

In this example pipeline it assumed that simple-cinc.xml contains the include element. Beside defining the include element it defines the namespache URI "http://apache.org/cocoon/include/1.0". This helps the CIncludeTransformer to find the tag to get replaced by the xml content referenced via the src attribute. The simple-cinc.xml may look like this:

<?xml version="1.0" encoding="UTF-8"?>
<page 
  xmlns:cinclude="http://apache.org/cocoon/include/1.0">
  <title>Hello</title>
  <content>
    <para>This is my first Cocoon page!</para>
    <cinclude:include src="include.xml" element="included"/>
  </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 CIncludeTransformer. I come from "include.xml". </p>

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

<?xml version="1.0" encoding="UTF-8"?>
<page 
  xmlns:cinclude="http://apache.org/cocoon/include/1.0">
  <title>Hello</title>
  <content>
    <para>This is my first Cocoon page!</para>
    <included>
      <p>
        I am <strong>included</strong> by CIncludeTransformer.
        I come from "include.xml".
      </p>
    </included>
  </content>
</page>

One feature of the cinclude transformer (this is currently not supported by the caching cinclude transformer) is including XML from external sources, e.g. files or from an HTTP server. The cinclude:includexml tag starts including of XML:


	<cinclude:includexml> <!-- Include XML from HTTP server --> <cinclude:src>http://external.news.com/flashnews.xml</cinclude:src> </cinclude:includexml>

This would be a simple way of "get"ting XML data from an external site. Using this method it is also possible to pass parameters in the url - just as you would in a "get" sent from a browser.


	<cinclude:includexml> <!-- Include XML from HTTP server --> <cinclude:src>http://external.news.com/flashnews.xml?id=1234&myname=matthew</cinclude:src> </cinclude:includexml>

If the external XML is not valid or not available, the transformer signals an error to the pipeline and the document containing the include command is not available.


	<cinclude:includexml ignoreErrors="true"> ... </cinclude:includexml>

The above section shows you how to include XML data from an external source such as an HTTP server using the simple "get" method supplied in the HTTP protocol. For more advanced uses you will wish to be able to send "Post" or other HTTP methods to the server. In addition you may want to actually send XML data to the server - just as you would using an HTML form. The format of this resource is slightly more complicated:

<?xml version="1.0"?>
<data xmlns:cinclude="http://apache.org/cocoon/include/1.0">
<cinclude:includexml>
    <cinclude:src>http://itsunshine/tamino/blah</cinclude:src>
    <cinclude:configuration>
	<cinclude:parameter>
	  <cinclude:name>method</cinclude:name>
	  <cinclude:value>POST</cinclude:value>
	</cinclude:parameter>
    </cinclude:configuration>
    <cinclude:parameters>
      <cinclude:parameter>
	  <cinclude:name>message</session:name>
	  <cinclude:value>Hi there</session:value>
	</cinclude:parameter>
	<cinclude:parameter>
	  <cinclude:name>_Process</cinclude:name>
	  <cinclude:value><name>matti</name><age>36</age></cinclude:value>
	</cinclude:param>
    </cinclude:parameters>
</cinclude:includexml>
</data>

Lets look at the tags. The tag cinclude:src defines the address of the resource we want to access and then comes a list of (optional) connection-specific parameters (enclosed in the cinclude:configuration tag). In this example the HTTP-method ("POST") is passed into the connection. The format of these parameters is discussed next.

Then comes the list of parameters we wish to pass into the function. Each parameter defined has a name and a value. The value can either be text or XML.