home *** CD-ROM | disk | FTP | other *** search
/ PC Professionell 2004 December / PCpro_2004_12.ISO / files / webserver / xampp / xampp-cocoon-addon-1.4.9-installer.exe / sourcewriting-transformer.xml < prev    next >
Encoding:
Extensible Markup Language  |  2004-07-12  |  13.1 KB  |  334 lines
  1. <?xml version="1.0" encoding="UTF-8"?>
  2. <!--
  3.   Copyright 1999-2004 The Apache Software Foundation
  4.  
  5.   Licensed under the Apache License, Version 2.0 (the "License");
  6.   you may not use this file except in compliance with the License.
  7.   You may obtain a copy of the License at
  8.  
  9.       http://www.apache.org/licenses/LICENSE-2.0
  10.  
  11.   Unless required by applicable law or agreed to in writing, software
  12.   distributed under the License is distributed on an "AS IS" BASIS,
  13.   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.   See the License for the specific language governing permissions and
  15.   limitations under the License.
  16. -->
  17. <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
  18.  
  19. <document>
  20.     <header>
  21.         <title>Source Writing Transformer</title>
  22.         <version>0.9</version>
  23.         <type>Technical document</type>
  24.         <authors>
  25.             <person name="Jeremy Quinn" email="jeremy@apache.org"/>
  26.         </authors>
  27.         <abstract>This document describes the Source Writing transformer of Cocoon.</abstract>
  28.     </header>
  29.     <body>
  30.         <s1 title="Source Writing Transformer">
  31.             <p>Diverts xml from a pipeline, writing it to a Source (or
  32.       deleting it).</p>
  33.             <p>Thankfully, <code>FileSource</code> is no longer the only <code>Source</code> that currently implements <code>WritableSource</code>; there are implementations of WebDAV and Apache Slide WritableSources in the scratchpad. Hopefully further <code>ModifiableSource</code> implementations (XMLDB, CVS, Email, SQL, etc.) will be appear in the future.</p>
  34.             <ul>
  35.                 <li>Name : write-source</li>
  36.                 <li>Class: org.apache.cocoon.transformation.SourceWritingTransformer</li>
  37.                 <li>Cacheable: no.</li>
  38.             </ul>
  39.         </s1>
  40.         <s1 title="The Tags">
  41.                 <source>
  42.                     <![CDATA[
  43.         <source:write>
  44.             [<source:path/>]
  45.             <source:source/>
  46.             <source:fragment/>
  47.         </source:write>
  48.         
  49.         <source:insert/>
  50.             <source:path/>
  51.             <source:source/>
  52.             <source:fragment/>
  53.             [<source:replace/>]
  54.             [<source:reinsert/>]
  55.         </source:insert>
  56.  
  57.         <source:delete/>
  58.             <source:source/>
  59.             [<source:path/>] - Ignored
  60.             [<source:fragment/>] - Ignored
  61.             [<source:replace/>] - Ignored
  62.             [<source:reinsert/>] - Ignored
  63.         </source:insert>
  64.                     ]]>
  65.                 </source>
  66.             <p>In the namespace <code>xmlns:source="http://apache.org/cocoon/source/1.0"</code>.</p>
  67.             <p>The contents of the <code><![CDATA[<source:fragment/>]]></code>
  68.       tag are written to the specified ModifiableSource when the
  69.       document containing it is transformed by SourceWritingTransformer
  70.       (or deleted if you are using the <code>delete </code>instruction).</p>
  71.         </s1>
  72.         <s1 title="Definition">
  73.                 <source>
  74.                     <![CDATA[
  75.  <map:transformer name="write-source" 
  76.     src="org.apache.cocoon.transformation.SourceWritingTransformer">
  77.         <map:parameter name="serializer" value="xml"/>  
  78.  </map:transformer/>
  79.                     ]]>
  80.                 </source>
  81.             <p>The SourceWritingTransformer is predefined for you in the main SiteMap.</p>
  82.         </s1>
  83.         <s1 title="Invocation">
  84.             <p>This invokes the SourceWritingTransformer on your pipeline.</p>
  85.                 <source>
  86.                     <![CDATA[
  87.  <map:transform type="write-source"/>
  88.                     ]]>
  89.                 </source>
  90.             <p>Or you can over-ride the default serializer here.</p>
  91.                 <source>
  92.                     <![CDATA[
  93.  <map:transform type="write-source">
  94.    <map:parameter name="serializer" value="my-special-serializer"/>   
  95.  </map:transform>
  96.                     ]]>
  97.                 </source>
  98.         </s1>
  99.  
  100.         <s1 title="The Tags in detail">
  101.             <s2 title="source:write">
  102.                 <p>The source:write tag can take optional attributes, <code>create</code> (defaults to 'true') and <code>serializer</code> (defaults to the serializer set up in the definition or invocation of the transformer).</p>
  103.                 <p>Replaces the entire content of a <code>Source</code> (specified by the <code><![CDATA[<source:source/>]]></code> tag) with the contents of the <code><![CDATA[<source:fragment/>]]></code> tag, if @create is 'true', a new asset will be created if one does not already exist.</p>
  104.                 <p>The <code><![CDATA[<source:source/>]]></code> and <code><![CDATA[<source:fragment/>]]></code> tags are required, a <code><![CDATA[<source:path/>]]></code> tag is optional, if specified, the value is an used as an XPath to generate xml in your <code>Source</code>, inwhich to wrap your content.</p>
  105.                 <s3 title="source:source">
  106.                     <p>The System ID of the <code>Source</code> to be written to.</p>
  107.                     <p>eg: <code><![CDATA[<source:source>docs/blah.xml</source:source>]]></code> or <code><![CDATA[<source:source>context:/blah.xml</source:source>]]></code> etc.</p>
  108.                 </s3>
  109.                 <s3 title="source:fragment">
  110.                     <p>The XML Fragment to be written.</p>
  111.                     <p>eg: </p>
  112.                         <source>
  113.                             <![CDATA[
  114.     <source:fragment><foo>
  115.             <bar id="dogcow"/>
  116.         </foo></source:fragment>
  117.                             ]]>
  118.                         </source> 
  119.                         <p>or</p>
  120.                         <source>
  121.                             <![CDATA[
  122.     <source:fragment>
  123.         <foo/>
  124.         <bar>
  125.             <dogcow/>
  126.         <bar/>
  127.     </source:fragment>
  128.                             ]]>
  129.                         </source> 
  130.                         <p>etc.</p>
  131.  
  132.                     <note>The second example type, can only be used when the <code><![CDATA[<source:path/>]]></code> tag has been specified.</note>
  133.                 </s3>
  134.                 <s3 title="source:path">
  135.                     <p>[Optional] XPath to specify how your content is wrapped</p>
  136.                     <p>eg: <code><![CDATA[<source:path>doc</source:path>]]></code> - your content is placed inside a <code><![CDATA[<doc/>]]></code> root tag.</p>
  137.                     <note>If this parameter is omitted, your content MUST have only ONE top-level node.</note>
  138.                 </s3>
  139.              </s2>
  140.  
  141.             <s2 title="source:insert">
  142.                 <p>The source:insert tag can take optional attributes, <code>create</code> (defaults to 'true') and <code>serializer</code> (defaults to the serializer set up in the definition or invocation of the transformer).</p>
  143.                 <p>Inserts into a <code>Source</code> (specified by the <code><![CDATA[<source:source/>]]></code> tag) the contents of the tag <code><![CDATA[<source:fragment/>]]></code> at the XPath location specified in the <code><![CDATA[<source:path/>]]></code> tag, if @create is 'true', a new <code>Source</code> will be created if one does not already exist.</p>
  144.                 <p>The <code><![CDATA[<source:source/>]]></code>, <code><![CDATA[<source:path/>]]></code> and <code><![CDATA[<source:fragment/>]]></code> tags are all required, the <code><![CDATA[<source:replace/>]]></code> and <code><![CDATA[<source:reinsert/>]]></code> tags are optional.</p>
  145.                 <s3 title="source:source">
  146.                     <p>The System ID of the <code>Source</code> to be inserted into.</p>
  147.                     <p>eg: <code><![CDATA[<source:source>docs/blah.xml</source:source>]]></code> or <code><![CDATA[<source:source>context:/blah.xml</source:source>]]></code> etc.</p>
  148.                 </s3>
  149.                 <s3 title="source:fragment">
  150.                     <p>The XML Fragment to be written.</p>
  151.                     <p>eg:</p>
  152.                         <source>
  153.                             <![CDATA[
  154.     <source:fragment>
  155.         <foo>
  156.             <bar id="dogcow"/>
  157.         </foo>
  158.     </source:fragment>
  159.                             ]]>
  160.                         </source> 
  161.                         <p>or</p>
  162.                         <source>
  163.                             <![CDATA[
  164.     <source:fragment>
  165.         <foo/>
  166.         <bar>
  167.             <dogcow/>
  168.         <bar/>
  169.     </source:fragment>
  170.                             ]]>
  171.                         </source> 
  172.                         <p>etc.</p>
  173.                 </s3>
  174.                 <s3 title="source:path">
  175.                     <p></p>
  176.                 </s3>
  177.                 <s3 title="source:replace">
  178.                     <p>[Optional] XPath (from <code><![CDATA[<source:path/>]]></code>) to select the node that is replaced by your new content</p>
  179.                     <p>eg: <code><![CDATA[<source:replace>foo/bar/dogcow/@status='cut'</source:replace>]]></code> (is equivalent to this in XSLT: <code>select="foo[bar/dogcow/@status='cut']"</code>), what gets replaced is the <code><![CDATA[<foo/>]]></code> which has a <code><![CDATA[<bar/>]]></code> with a <code><![CDATA[<dogcow status="cut"/>]]></code> in it.</p>
  180.                     <p>The <code>overwrite</code> attribute of the parent <code><![CDATA[<source:insert/>]]></code> is used to check if replacing is allowed. If <code>overwrite</code> is 'true' (the default) the node is replaced. If <code>overwrite</code> is 'false' the node is only inserted if the replace node is found.</p>
  181.                 </s3>
  182.                 <s3 title="source:reinsert">
  183.                     <p>[Optional] The XPath (relative to <code><![CDATA[<source:replace/>]]></code>) to backup the contents of the overwritten node to.</p>
  184.                     <p>eg: <code><![CDATA[<source:reinsert>foo/versions</source:reinsert>]]></code> or <code><![CDATA[<source:reinsert>/doc/versions/foo</source:reinsert>]]></code>.</p>
  185.                     <p>If specified and a node is replaced, all children of this replaced node will be reinserted at the given path.</p>
  186.                 </s3>
  187.              </s2>
  188.             <s2 title="Notes">
  189.                     <ul>
  190.                         <li>if 'replace' is not specified, your 'fragment' is appended as a child of 'path'.</li>
  191.                         <li>if 'replace' is specified and it exists and 'overwrite' is true, your 'fragment' is inserted in 'path', before 'replace' and then 'replace' is deleted.</li>
  192.                         <li>if 'replace' is specified and it exists and 'overwrite' is false, no action occurs.</li>
  193.                         <li>if 'replace' is specified and it does not exist and 'overwrite' is true, your 'fragment' is appended as a child of 'path'.</li>
  194.                         <li>if 'replace' is specified and it does not exist and 'overwrite' is false, your 'fragment' is appended as a child of 'path'.</li>
  195.                         <li>if 'reinsert' is specified and it does not exist, no action occurs.</li>
  196.                     </ul>
  197.             </s2>
  198.       <s2 title="source:delete">
  199.          <p>This instruction takes only a <code><![CDATA[<source:source/>]]></code>
  200.          parameter (as a child tag) and deletes the corresponding
  201.          source. All other <code>source:*</code> tags are ignored, if
  202.          present: this allows for easy source-write instructions to be
  203.          generated on the fly (e.g. by a stylesheet). Just change 
  204.          <code>source:write</code> to <code>source:delete</code> and
  205.          you're set.
  206.          </p>
  207.       </s2>
  208.         </s1>
  209.         
  210.         <s1 title="Examples">
  211.             <s2 title="Simple Write">
  212.                     <source>
  213.                         <![CDATA[
  214.  <page>
  215.    ...
  216.    <source:write xmlns:source="http://apache.org/cocoon/source/1.0">
  217.      <source:source>context://doc/editable/my.xml</source:source>      
  218.      <source:fragment><page>
  219.        <title>Hello World</title>
  220.        <content>
  221.          <p>This is my first paragraph.</p>
  222.        </content>
  223.      </page></source:fragment>
  224.    </source:write>
  225.    ...
  226.  </page>
  227.                         ]]>
  228.                     </source>
  229.             </s2>
  230.             <s2 title="Insert at end">
  231.                     <source>
  232.                         <![CDATA[
  233.  <page>
  234.    ...
  235.    <source:insert xmlns:source="http://apache.org/cocoon/source/1.0">
  236.      <source:source>context://doc/editable/my.xml</source:source>      
  237.      <source:path>page/content</source:path>      
  238.      <source:fragment>
  239.        <p>This paragraph gets <emp>inserted</emp>.</p>
  240.        <p>With this one, at the end of the content.</p>
  241.      </source:fragment>
  242.    </source:insert>
  243.    ...
  244.  </page>
  245.                         ]]>
  246.                     </source>
  247.             </s2>
  248.             <s2 title="Replace">
  249.                     <source>
  250.                         <![CDATA[
  251.  <page>
  252.    ...
  253.    <source:insert xmlns:source="http://apache.org/cocoon/source/1.0">
  254.      <source:source>context://doc/editable/my.xml"</source:source>      
  255.      <source:path>page/content</source:path>      
  256.      <source:replace>p[1]</source:replace>      
  257.      <source:fragment>
  258.        <p>This paragraph <emp>replaces</emp> the first paragraph.</p>
  259.      </source:fragment>
  260.    </source:insert>
  261.    ...
  262.  </page>
  263.                         ]]>
  264.                     </source>
  265.             </s2>
  266.             <s2 title="Insert at the beginning">
  267.                     <source>
  268.                         <![CDATA[
  269.  <page>
  270.    ...
  271.    <source:insert>
  272.      <source:source>context://doc/editable/my.xml</source:source>
  273.      <source:path>page</source:path>
  274.      <source:replace>content</source:replace>
  275.      <source:reinsert>content</source:reinsert>
  276.      <source:fragment>
  277.        <content>
  278.          <p>This new paragraph gets inserted <emp>before</emp> the other ones.</p>
  279.        </content>
  280.      </source:fragment>
  281.     <source:insert>
  282.    ...
  283.  </page>
  284.                         ]]>
  285.                     </source>
  286.                     <p>This sample does not currently work, see the tests in the scratchpad at <code>http://localhost:8080/cocoon/mount/editor/tests</code>.</p>
  287.                     <note>You must have built Cocoon with the scratchpad included for this link to work.</note>
  288.             </s2>
  289.             <s2 title="Delete a source">
  290.                     <source>
  291.                         <![CDATA[
  292.  <page>
  293.    ...
  294.    <source:delete>
  295.      <source:source>context://doc/editable/my.xml</source:source>
  296.    <source:delete>
  297.    ...
  298.  </page>
  299.                         ]]>
  300.             </source>
  301.  
  302.       </s2>
  303.             <s2 title="Sample of the output of these tags">
  304.                 <p>This is the kind of information that the <code>SourceWritingTransformer</code> outputs to the pipeline, replacing the original <code>source:write</code> and <code>source:insert</code> tags</p>
  305.                     <source>
  306.                         <![CDATA[
  307.  <page>
  308.    ...
  309.    <sourceResult>
  310.      <action>new|overwritten|none</action>
  311.      <behaviour>write|insert<behaviour>
  312.      <execution>success|failure</execution>
  313.      <serializer>xml</serializer>
  314.      <source>source:specific/path/to/context/doc/editable/my.xml</source>
  315.      <message>a message about what happened</message>
  316.    </sourceResult>
  317.    ...
  318.  </page>
  319.                         ]]>
  320.                     </source>
  321.             </s2>
  322.         </s1>
  323.         <s1 title="Known Problems">
  324.             <p>Namespace handling: namespace declarations are not copied to the <code>Source</code>, resulting in invalid XML.</p>
  325.             <p>I cannot get the 'insert before' example working, which uses the <code><![CDATA[<source:reinsert/>]]></code> tag.</p>
  326.         </s1>
  327.         <s1 title="Warning">
  328.             <p>It is not known how robust this transformer is under even moderate load, especially when it comes to more than one person modifying the same file at the same time.</p>
  329.         </s1>
  330.     </body>
  331. </document>
  332.  
  333.  
  334.