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>
-        &lt;cinclude:includexml&gt;  &lt;!-- Include XML from HTTP server --&gt;
-        &lt;cinclude:src&gt;http://external.news.com/flashnews.xml&lt;/cinclude:src&gt;
-        &lt;/cinclude:includexml&gt;
+        &lt;!-- Include XML from HTTP server --&gt;
+        &lt;cinclude:include src="http://external.news.com/flashnews.xml"/&gt;
       </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>
-        &lt;cinclude:includexml&gt;  &lt;!-- Include XML from HTTP server --&gt;
-        &lt;cinclude:src&gt;http://external.news.com/flashnews.xml?id=1234&amp;myname=matthew&lt;/cinclude:src&gt;
-        &lt;/cinclude:includexml&gt;
+        &lt;cinclude:include
+          src="http://external.news.com/flashnews.xml?id=1234&amp;myname=matthew"/&gt;
       </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>
-        &lt;cinclude:includexml ignoreErrors="true"&gt;
-          ...
-        &lt;/cinclude:includexml&gt;
-      </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>
-        &lt;?xml version="1.0"?&gt;
-        &lt;data xmlns:cinclude="http://apache.org/cocoon/include/1.0"&gt;
-        &lt;cinclude:includexml&gt;
+  &lt;?xml version="1.0"?&gt;
+  &lt;data xmlns:cinclude="http://apache.org/cocoon/include/1.0"&gt;
+    &lt;cinclude:includexml ignoreErrors="true"&gt;
         &lt;cinclude:src&gt;http://itsunshine/tamino/blah&lt;/cinclude:src&gt;
-        &lt;cinclude:configuration&gt;
+      &lt;cinclude:configuration&gt;
         &lt;cinclude:parameter&gt;
-        &lt;cinclude:name&gt;method&lt;/cinclude:name&gt;
-        &lt;cinclude:value&gt;POST&lt;/cinclude:value&gt;
+          &lt;cinclude:name&gt;method&lt;/cinclude:name&gt;
+          &lt;cinclude:value&gt;POST&lt;/cinclude:value&gt;
         &lt;/cinclude:parameter&gt;
-        &lt;/cinclude:configuration&gt;
-        &lt;cinclude:parameters&gt;
+      &lt;/cinclude:configuration&gt;
+      &lt;cinclude:parameters&gt;
         &lt;cinclude:parameter&gt;
-        &lt;cinclude:name&gt;message&lt;/cinclude:name&gt;
-        &lt;cinclude:value&gt;Hi there&lt;/cinclude:value&gt;
+          &lt;cinclude:name&gt;message&lt;/cinclude:name&gt;
+          &lt;cinclude:value&gt;Hi there&lt;/cinclude:value&gt;
         &lt;/cinclude:parameter&gt;
         &lt;cinclude:parameter&gt;
-        &lt;cinclude:name&gt;_Process&lt;/cinclude:name&gt;
-        &lt;cinclude:value&gt;&lt;name&gt;matti&lt;/name&gt;&lt;age&gt;36&lt;/age&gt;&lt;/cinclude:value&gt;
+          &lt;cinclude:name&gt;_Process&lt;/cinclude:name&gt;
+          &lt;cinclude:value&gt;&lt;name&gt;matti&lt;/name&gt;&lt;age&gt;36&lt;/age&gt;&lt;/cinclude:value&gt;
         &lt;/cinclude:parameter&gt;
-        &lt;/cinclude:parameters&gt;
-        &lt;/cinclude:includexml&gt;
-        &lt;/data&gt;
+      &lt;/cinclude:parameters&gt;
+    &lt;/cinclude:includexml&gt;
+  &lt;/data&gt;
       </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>
+        &lt;map:parameter name="support-caching" value="true"/&gt;
+      </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>