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="[EMAIL PROTECTED]"/>
</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: [EMAIL PROTECTED]
To unsubscribe, e-mail: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
