cocoon-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From jer...@apache.org
Subject cvs commit: xml-cocoon2/src/documentation/xdocs/userdocs/transformers sourcewriting-transformer.xml book.xml transformers.xml
Date Wed, 03 Jul 2002 19:39:55 GMT
jeremy      2002/07/03 12:39:54

  Modified:    src/documentation/xdocs/userdocs/transformers book.xml
                        transformers.xml
  Added:       src/documentation/xdocs/userdocs/transformers
                        sourcewriting-transformer.xml
  Log:
  adding documentation for SourceWritingTransformer
  
  Revision  Changes    Path
  1.3       +1 -0      xml-cocoon2/src/documentation/xdocs/userdocs/transformers/book.xml
  
  Index: book.xml
  ===================================================================
  RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/transformers/book.xml,v
  retrieving revision 1.2
  retrieving revision 1.3
  diff -u -r1.2 -r1.3
  --- book.xml	30 Jun 2002 10:48:12 -0000	1.2
  +++ book.xml	3 Jul 2002 19:39:54 -0000	1.3
  @@ -27,6 +27,7 @@
       <menu-item label="XInclude Transformer" href="xinclude-transformer.html"/>
       <menu-item label="CInclude Transformer" href="cinclude-transformer.html"/>
       <menu-item label="EncodeURL Transformer" href="encodeurl-transformer.html"/>
  +    <menu-item label="SourceWriting Transformer" href="sourcewriting-transformer.html"/>
     </menu>
     <menu label="Optional">
       <menu-item label="XT Transformer" href="xt-transformer.html"/>
  
  
  
  1.4       +1 -0      xml-cocoon2/src/documentation/xdocs/userdocs/transformers/transformers.xml
  
  Index: transformers.xml
  ===================================================================
  RCS file: /home/cvs/xml-cocoon2/src/documentation/xdocs/userdocs/transformers/transformers.xml,v
  retrieving revision 1.3
  retrieving revision 1.4
  diff -u -r1.3 -r1.4
  --- transformers.xml	30 Jun 2002 10:48:12 -0000	1.3
  +++ transformers.xml	3 Jul 2002 19:39:54 -0000	1.4
  @@ -40,6 +40,7 @@
   				<li><link href="xinclude-transformer.html">XInclude Transformer</link></li>
   				<li><link href="cinclude-transformer.html">CInclude Transformer</link></li>
   				<li><link href="encodeurl-transformer.html">EncodeURL Transformer</link></li>
  +				<li><link href="sourcewriting-transformer.html">SourceWriting Transformer</link></li>
   				<li><link href="xt-transformer.html">XT Transformer</link> (optional)</li>
   				<li><link href="ldap-transformer.html">LDAP Transformer</link> (optional)</li>
   			</ul>
  
  
  
  1.1                  xml-cocoon2/src/documentation/xdocs/userdocs/transformers/sourcewriting-transformer.xml
  
  Index: sourcewriting-transformer.xml
  ===================================================================
  <?xml version="1.0" encoding="UTF-8"?>
  <!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "../../dtd/document-v10.dtd">
  
  <document>
  	<header>
  		<title>Source Writing Transformer</title>
  		<version>0.9</version>
  		<type>Technical document</type>
  		<authors>
  			<person name="Jeremy Quinn" email="jeremy@apache.org"/>
  		</authors>
  		<abstract>This document describes the Source Writing transformer of Cocoon.</abstract>
  	</header>
  	<body>
  		<s1 title="Source Writing Transformer">
  			<p>Diverts xml from a pipeline, writing it to a Source.</p>
  			<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>WriteableSource</code>
implementations (XMLDB, CVS, Email, SQL, etc.) will be appear in the future.</p>
  			<ul>
  				<li>Name : write-source</li>
  				<li>Class: org.apache.cocoon.transformation.SourceWritingTransformer</li>
  				<li>Cacheable: no.</li>
  			</ul>
  			<p>If you have built Cocoon with the ScratchPad included (using: <code>./build.sh
 -Dinclude.webapp.libs=yes -Dinclude.scratchpad.libs=yes webapp</code>), there are a
set of <link href="../../../mount/editor/">samples</link> set up, including <link
href="../../../mount/editor/tests">tests</link> and a demonstration editor, <link
href="../../../mount/editor/edit/">&lt;slash-edit/&gt;</link></p>
  			<note>Please beware of putting these samples on a public-facing server.</note>
  		</s1>
  		<s1 title="The Tags">
  			<p>
  				<source>
  					<![CDATA[
  		<source:write>
  			[<source:path/>]
  			<source:source/>
  			<source:fragment/>
  		</source:write>
  		
  		<source:insert/>
  			<source:path/>
  			<source:source/>
  			<source:fragment/>
  			[<source:replace/>]
  			[<source:reinsert/>]
  		</source:insert>
  					]]>
  				</source>
  			</p>
  			<p>In the namespace <code>xmlns:source="http://apache.org/cocoon/source/1.0"</code>.</p>
  			<p>The contents of the <code><![CDATA[<source:fragment/>]]></code>
tag are written to the specified WriteableSource when the document containing it is transformed
by SourceWritingTransformer.</p>
  		</s1>
  		<s1 title="Definition">
  			<p>
  				<source>
  					<![CDATA[
   <map:transformer name="write-source" src="org.apache.cocoon.transformation.SourceWritingTransformer">
  		<map:parameter name="serializer" value="xml"/>  
   </map:transformer/>
  					]]>
  				</source>
  			</p>
  			<p>The SourceWritingTransformer is predefined for you in the main SiteMap.</p>
  		</s1>
  		<s1 title="Invocation">
  			<p>This invokes the SourceWritingTransformer on your pipeline.</p>
  			<p>
  				<source>
  					<![CDATA[
   <map:transform type="write-source"/>
  					]]>
  				</source>
  			</p>
  			<p>Or you can over-ride the default serializer here.</p>
  			<p>
  				<source>
  					<![CDATA[
   <map:transform type="write-source">
     <map:parameter name="serializer" value="my-special-serializer"/>   
   </map:transform>
  					]]>
  				</source>
  			</p>
  		</s1>
  
  		<s1 title="The Tags in detail">
  			<s2 title="source:write">
  				<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>
  				<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>
  				<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>
  				<s3 title="source:source">
  					<p>The System ID of the <code>Source</code> to be written to.</p>
  					<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>
  				</s3>
  				<s3 title="source:fragment">
  					<p>The XML Fragment to be written.</p>
  					<p>eg: 
  						<source>
  							<![CDATA[
  	<source:fragment><foo>
  			<bar id="dogcow"/>
  		</foo></source:fragment>
  							]]>
  						</source> 
  						or
  						<source>
  							<![CDATA[
  	<source:fragment>
  		<foo/>
  		<bar>
  			<dogcow/>
  		<bar/>
  	</source:fragment>
  							]]>
  						</source> 
  						etc.
  					</p>
  					<note>The second example type, can only be used when the <code><![CDATA[<source:path/>]]></code>
tag has been specified.</note>
  				</s3>
  				<s3 title="source:path">
  					<p>[Optional] XPath to specify how your content is wrapped</p>
  					<p>eg: <code><![CDATA[<source:path>doc</source:path>]]></code>
- your content is placed inside a <code><![CDATA[<doc/>]]></code>
root tag.</p>
  					<note>If this parameter is omitted, your content MUST have only ONE top-level
node.</note>
  				</s3>
   			</s2>
  
  			<s2 title="source:insert">
  				<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>
  				<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>
  				<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>
  				<s3 title="source:source">
  					<p>The System ID of the <code>Source</code> to be inserted into.</p>
  					<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>
  				</s3>
  				<s3 title="source:fragment">
  					<p>The XML Fragment to be written.</p>
  					<p>eg: 
  						<source>
  							<![CDATA[
  	<source:fragment>
  		<foo>
  			<bar id="dogcow"/>
  		</foo>
  	</source:fragment>
  							]]>
  						</source> 
  						or
  						<source>
  							<![CDATA[
  	<source:fragment>
  		<foo/>
  		<bar>
  			<dogcow/>
  		<bar/>
  	</source:fragment>
  							]]>
  						</source> 
  						etc.
  					</p>
  				</s3>
  				<s3 title="source:path">
  					<p></p>
  				</s3>
  				<s3 title="source:replace">
  					<p>[Optional] XPath (from <code><![CDATA[<source:path/>]]></code>)
to select the node that is replaced by your new content</p>
  					<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>
  					<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>
  				</s3>
  				<s3 title="source:reinsert">
  					<p>[Optional] The XPath (relative to <code><![CDATA[<source:replace/>]]></code>)
to backup the contents of the overwritten node to.</p>
  					<p>eg: <code><![CDATA[<source:reinsert>foo/versions</source:reinsert>]]></code>
or <code><![CDATA[<source:reinsert>/doc/versions/foo</source:reinsert>]]></code>.</p>
  					<p>If specified and a node is replaced, all children of this replaced node will
be reinserted at the given path.</p>
  				</s3>
   			</s2>
  			<s2 title="Notes">
  				<p>
  					<ul>
  						<li>if 'replace' is not specified, your 'fragment' is appended as a child of
'path'.</li>
  						<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>
  						<li>if 'replace' is specified and it exists and 'overwrite' is false, no action
occurs.</li>
  						<li>if 'replace' is specified and it does not exist and 'overwrite' is true,
your 'fragment' is appended as a child of 'path'.</li>
  						<li>if 'replace' is specified and it does not exist and 'overwrite' is false,
your 'fragment' is appended as a child of 'path'.</li>
  						<li>if 'reinsert' is specified and it does not exist, no action occurs.</li>
  					</ul>
  				</p>
  			</s2>
  		</s1>
  		
  		<s1 title="Examples">
  			<s2 title="Simple Write">
  				<p>
  					<source>
  						<![CDATA[
   <page>
     ...
     <source:write xmlns:source="http://apache.org/cocoon/source/1.0">
       <source:source>context://doc/editable/my.xml</source:source>      
       <source:fragment><page>
         <title>Hello World</title>
         <content>
           <p>This is my first paragraph.</p>
         </content>
       </page></source:fragment>
     </source:write>
     ...
   </page>
  						]]>
  					</source>
  				</p>
  			</s2>
  			<s2 title="Insert at end">
  				<p>
  					<source>
  						<![CDATA[
   <page>
     ...
     <source:insert xmlns:source="http://apache.org/cocoon/source/1.0">
       <source:source>context://doc/editable/my.xml</source:source>      
       <source:path>page/content</source:path>      
       <source:fragment>
         <p>This paragraph gets <emp>inserted</emp>.</p>
         <p>With this one, at the end of the content.</p>
       </source:fragment>
     </source:insert>
     ...
   </page>
  						]]>
  					</source>
  				</p>
  			</s2>
  			<s2 title="Replace">
  				<p>
  					<source>
  						<![CDATA[
   <page>
     ...
     <source:insert xmlns:source="http://apache.org/cocoon/source/1.0">
       <source:source>context://doc/editable/my.xml"</source:source>      
       <source:path>page/content</source:path>      
       <source:replace>p[1]</source:replace>      
       <source:fragment>
         <p>This paragraph <emp>replaces</emp> the first paragraph.</p>
       </source:fragment>
     </source:insert>
     ...
   </page>
  						]]>
  					</source>
  				</p>
  			</s2>
  			<s2 title="Insert at the beginning">
  				<p>
  					<source>
  						<![CDATA[
   <page>
     ...
     <source:insert>
       <source:source>context://doc/editable/my.xml</source:source>
       <source:path>page</source:path>
       <source:replace>content</source:replace>
       <source:reinsert>content</source:reinsert>
       <source:fragment>
         <content>
           <p>This new paragraph gets inserted <emp>before</emp> the other
ones.</p>
         </content>
       </source:fragment>
      <source:insert>
     ...
   </page>
  						]]>
  					</source>
  					<p>This sample does not currently work, see the <link href="../../../mount/editor/tests">tests</link>
in the scratchpad.</p>
  					<note>You must have built Cocoon with the scratchpad included for this link to
work.</note>
  				</p>
  			</s2>
  			<s2 title="Sample of the output of these tags">
  				<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>
  				<p>
  					<source>
  						<![CDATA[
   <page>
     ...
     <sourceResult>
       <action>new|overwritten|none</action>
       <behaviour>write|insert<behaviour>
       <execution>success|failure</execution>
       <serializer>xml</serializer>
       <source>source:specific/path/to/context/doc/editable/my.xml</source>
       <message>a message about what happened</message>
     </sourceResult>
     ...
   </page>
  						]]>
  					</source>
  				</p>
  			</s2>
  		</s1>
  		<s1 title="Known Problems">
  			<p>Namespace handling: namespace declarations are not copied to the <code>Source</code>,
resulting in invalid XML.</p>
  			<p>I cannot get the 'insert before' example working, which uses the <code><![CDATA[<source:reinsert/>]]></code>
tag.</p>
  		</s1>
  		<s1 title="Warning">
  			<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>
  		</s1>
  	</body>
  </document>
  
  
  
  
  

----------------------------------------------------------------------
In case of troubles, e-mail:     webmaster@xml.apache.org
To unsubscribe, e-mail:          cocoon-cvs-unsubscribe@xml.apache.org
For additional commands, e-mail: cocoon-cvs-help@xml.apache.org


Mime
View raw message