You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by vg...@apache.org on 2005/05/27 16:49:37 UTC
svn commit: r178786 -
/cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml
Author: vgritsenko
Date: Fri May 27 07:49:35 2005
New Revision: 178786
URL: http://svn.apache.org/viewcvs?rev=178786&view=rev
Log:
regular syntax supports remote servers just fine.
fix bug #30432 - add supports-caching parameter.
Modified:
cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml
Modified: cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml
URL: http://svn.apache.org/viewcvs/cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml?rev=178786&r1=178785&r2=178786&view=diff
==============================================================================
--- cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml (original)
+++ cocoon/branches/BRANCH_2_1_X/src/documentation/xdocs/userdocs/transformers/cinclude-transformer.xml Fri May 27 07:49:35 2005
@@ -20,7 +20,7 @@
<header>
<title>CInclude Transformer</title>
<subtitle>in @doctitle@</subtitle>
- <version>0.9</version>
+ <version>$Id$</version>
<type>Technical document</type>
<authors>
<person name="Carsten Ziegeler" email="cziegeler@apache.org"/>
@@ -35,7 +35,7 @@
the transformer: one verbose and flexible approach, and a simple approach.
We will first discuss the simple approach and
the more flexible is mentioned in the next chapter. In addition
- the cinclude transformer provides a caching mechanism (for the
+ the CInclude transformer provides a caching mechanism (for the
simple include form).</p>
<p>This transformer triggers for the element <code>include</code> in the
@@ -48,7 +48,7 @@
<ul>
<li>Name : cinclude</li>
<li>Class: org.apache.cocoon.transformation.CIncludeTransformer</li>
- <li>Cacheable: no.</li>
+ <li>Cacheable: No.</li>
</ul>
<p>A simple example might help to use the CIncludeTransfomer effectively:</p>
@@ -56,146 +56,136 @@
<p>Add the CIncludeTransformer to the components in your sitemap.xmap</p>
<source><![CDATA[
-...
-<map:components>
-...
-<map:transformers default="xslt">
-...
-<map:transformer name="cinclude"
-src="org.apache.cocoon.transformation.CIncludeTransformer"/>
-...
+ <map:components>
+ ...
+ <map:transformers default="xslt">
+ ...
+ <map:transformer name="cinclude"
+ src="org.apache.cocoon.transformation.CIncludeTransformer"/>
+ ...
]]></source>
<p>Next, define in your pipeline to use the CIncludeTransformer</p>
<source><![CDATA[
-<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>
+ <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>
]]></source>
- <p>In this example pipeline it assumed that simple-cinc.xml contains
- the include element. Beside defining the include element
- it defines the namespace URI "http://apache.org/cocoon/include/1.0".
- This helps the CIncludeTransformer to find the tag to get replaced by
+ <p>In this example pipeline it assumed that <code>simple-cinc.xml</code>
+ contains the include element. Beside defining the include element
+ it defines the namespace URI <code>http://apache.org/cocoon/include/1.0</code>.
+ This helps the CInclude transformer to find the tag to get replaced by
the xml content referenced via the src attribute.
- The simple-cinc.xml may look like this:</p>
+ The <code>simple-cinc.xml</code> may look like this:</p>
<source><![CDATA[
-<?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>
+ <?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>
]]></source>
- <p>Next you should define the include.xml file which is included.
- A simple include.xml might look like this:</p>
+ <p>Next you should define the <code>include.xml</code> file which is
+ included. A simple <code>include.xml</code> might look like this:</p>
<source><![CDATA[
-<?xml version="1.0"?>
-<p>
-I am <strong>included</strong> by CIncludeTransformer.
-I come from "include.xml".
-</p>
+ <?xml version="1.0"?>
+ <p>
+ I am <strong>included</strong> by CIncludeTransformer.
+ I come from "include.xml".
+ </p>
]]></source>
<p>Now finally we have everything put together the xml content after
- the CIncludeTransformer processing will look like this:</p>
+ the CInclude transformer processing will look like this:</p>
<source><![CDATA[
-<?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>
+ <?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>
]]></source>
</s1>
- <s1 title="Including External XML (simple)">
- <p>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 <code>cinclude:includexml</code> tag starts including of XML:</p>
+ <s1 title="Including External XML">
+ <p>One feature of the CInclude transformer is including XML from
+ external sources, e.g. files or from an HTTP server.</p>
<source>
- <cinclude:includexml> <!-- Include XML from HTTP server -->
- <cinclude:src>http://external.news.com/flashnews.xml</cinclude:src>
- </cinclude:includexml>
+ <!-- Include XML from HTTP server -->
+ <cinclude:include src="http://external.news.com/flashnews.xml"/>
</source>
- <p>This would be a simple way of "get"ting XML data from an
+ <p>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.</p>
+ url - just as you would in a "GET" sent from a browser.</p>
<source>
- <cinclude:includexml> <!-- Include XML from HTTP server -->
- <cinclude:src>http://external.news.com/flashnews.xml?id=1234&myname=matthew</cinclude:src>
- </cinclude:includexml>
+ <cinclude:include
+ src="http://external.news.com/flashnews.xml?id=1234&myname=matthew"/>
</source>
<p>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.</p>
-
- <p>For this purpose the <code>ignoreErrors</code> attribute can be used:</p>
-
- <source>
- <cinclude:includexml ignoreErrors="true">
- ...
- </cinclude:includexml>
- </source>
+ transformer will throw an exception which can be processed by the sitemap
+ error handler.</p>
</s1>
<s1 title="Including External XML (advanced)">
<p>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
+ 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
+ "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:</p>
+ The syntax of the advanced include element is more verbose:</p>
+
<source>
- <?xml version="1.0"?>
- <data xmlns:cinclude="http://apache.org/cocoon/include/1.0">
- <cinclude:includexml>
+ <?xml version="1.0"?>
+ <data xmlns:cinclude="http://apache.org/cocoon/include/1.0">
+ <cinclude:includexml ignoreErrors="true">
<cinclude:src>http://itsunshine/tamino/blah</cinclude:src>
- <cinclude:configuration>
+ <cinclude:configuration>
<cinclude:parameter>
- <cinclude:name>method</cinclude:name>
- <cinclude:value>POST</cinclude:value>
+ <cinclude:name>method</cinclude:name>
+ <cinclude:value>POST</cinclude:value>
</cinclude:parameter>
- </cinclude:configuration>
- <cinclude:parameters>
+ </cinclude:configuration>
+ <cinclude:parameters>
<cinclude:parameter>
- <cinclude:name>message</cinclude:name>
- <cinclude:value>Hi there</cinclude:value>
+ <cinclude:name>message</cinclude:name>
+ <cinclude:value>Hi there</cinclude:value>
</cinclude:parameter>
<cinclude:parameter>
- <cinclude:name>_Process</cinclude:name>
- <cinclude:value><name>matti</name><age>36</age></cinclude:value>
+ <cinclude:name>_Process</cinclude:name>
+ <cinclude:value><name>matti</name><age>36</age></cinclude:value>
</cinclude:parameter>
- </cinclude:parameters>
- </cinclude:includexml>
- </data>
+ </cinclude:parameters>
+ </cinclude:includexml>
+ </data>
</source>
- <p>Lets look at the tags. The tag <code>cinclude:src</code> defines the address of the
+ <p>Lets look at the tags. The tag <code>cinclude:includexml</code>
+ identifies verbose include syntax. Attribute <code>ignoreErrors</code>
+ indicates that all errors will be simply ignored.</p>
+
+ <p>The tag <code>cinclude:src</code> defines the address of the
resource we want to access and then comes a list of (optional)
connection-specific parameters (enclosed in the <code>cinclude:configuration</code> tag).
In this example the HTTP-method ("POST") is passed into the connection. The
@@ -216,7 +206,14 @@
the content. If, in those cases, your content does not change too
frequently, you can turn on caching for these contents.</p>
- <p>To turn on caching, this transformer triggers for the element
+ <p>To turn on caching, transformer must be configured with sitemap
+ parameter:</p>
+
+ <source>
+ <map:parameter name="support-caching" value="true"/>
+ </source>
+
+ <p>Caching triggers <strong>only</strong> for the element
<code>cached-include</code> in the namespace
<code>http://apache.org/cocoon/include/1.0/caching</code>.
The <code>src</code> attribute contains the url which points to
@@ -233,14 +230,15 @@
parameter is explained below.</p>
<source><![CDATA[
-<map:match pattern="cinc/simple-cinc">
-<map:generate src="cinc/simple-cinc.xml"/>
-<map:transform type="cinclude">
-<map:parameter name="expires" value="600"/>
-</map:transform>
-<map:transform src="stylesheets/page/simple-page2html.xsl"/>
-<map:serialize/>
-</map:match>
+ <map:match pattern="cinc/simple-cinc">
+ <map:generate src="cinc/simple-cinc.xml"/>
+ <map:transform type="cinclude">
+ <map:parameter name="support-caching" value="true"/>
+ <map:parameter name="expires" value="600"/>
+ </map:transform>
+ <map:transform src="stylesheets/page/simple-page2html.xsl"/>
+ <map:serialize/>
+ </map:match>
]]></source>
<p>In this example-pipeline it is assumed that simple-cinc.xml
@@ -252,36 +250,34 @@
this:</p>
<source><![CDATA[
-<?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:cached-include src="http://server/document1.xml"/>
-<cinclude:cached-include src="http://server/document2.xml"/>
-</content>
-</page>
+ <?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:cached-include src="http://server/document1.xml"/>
+ <cinclude:cached-include src="http://server/document2.xml"/>
+ </content>
+ </page>
]]></source>
<p>Now finally we have everything put together the xml content after
the CIncludeTransformer processing will look like this:</p>
<source><![CDATA[
-<?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>
-<document1>
-CONTENT OF document 1
-</document1>
-<document2>
-CONTENT OF document 2
-</document2>
-</content>
-</page>
+ <?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>
+ <document1>
+ CONTENT OF document 1
+ </document1>
+ <document2>
+ CONTENT OF document 2
+ </document2>
+ </content>
+ </page>
]]></source>
<p>So, of course even with caching turned on, this transformer acts like the
@@ -319,18 +315,18 @@
<p>Complete Example:</p>
<source><![CDATA[
-<map:match pattern="cinc/simple-cinc">
-<map:generate src="cinc/simple-cinc.xml"/>
-<map:transform type="cinclude">
-<map:parameter name="expires" value="600"/>
-<map:parameter name="purge" value="false"/>
-<map:parameter name="parallel" value="true"/>
-<map:parameter name="preemptive" value="false"/>
-<map:parameter name="source" value="file:/c:/temp"/>
-</map:transform>
-<map:transform src="stylesheets/page/simple-page2html.xsl"/>
-<map:serialize/>
-</map:match>
+ <map:match pattern="cinc/simple-cinc">
+ <map:generate src="cinc/simple-cinc.xml"/>
+ <map:transform type="cinclude">
+ <map:parameter name="expires" value="600"/>
+ <map:parameter name="purge" value="false"/>
+ <map:parameter name="parallel" value="true"/>
+ <map:parameter name="preemptive" value="false"/>
+ <map:parameter name="source" value="file:/c:/temp"/>
+ </map:transform>
+ <map:transform src="stylesheets/page/simple-page2html.xsl"/>
+ <map:serialize/>
+ </map:match>
]]></source>
</s1>
@@ -353,23 +349,22 @@
<p>First you have to define the action:</p>
<source><![CDATA[
-...
-<map:components>
-...
-<map:actions>
-...
-<map:action name="preemptive"
-src="org.apache.cocoon.transformation.helpers.PreemptiveLoaderAction"/>
-...
+ <map:components>
+ ...
+ <map:actions>
+ ...
+ <map:action name="preemptive"
+ src="org.apache.cocoon.transformation.helpers.PreemptiveLoaderAction"/>
+ ...
]]></source>
<p>Then you must define a pipeline containing the action. This is the pipeline that
has to be configured in the cocoon.xconf:</p>
<source><![CDATA[
- <map:match pattern="loader">
- <map:act type="preemptive"></map:act>
- </map:match>
+ <map:match pattern="loader">
+ <map:act type="preemptive"></map:act>
+ </map:match>
]]></source>
</s1>
</body>