You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by je...@apache.org on 2002/07/03 21:39:55 UTC
cvs commit: xml-cocoon2/src/documentation/xdocs/userdocs/transformers sourcewriting-transformer.xml book.xml transformers.xml
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/"><slash-edit/></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