coliver 2003/07/19 20:02:20
Modified: src/documentation/xdocs/userdocs/flow api.xml jxforms.xml
sitemap.xml velocity.xml
Log:
Improve docs
Revision Changes Path
1.19 +15 -9 cocoon-2.1/src/documentation/xdocs/userdocs/flow/api.xml
Index: api.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/api.xml,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -r1.18 -r1.19
--- api.xml 14 Jul 2003 09:36:41 -0000 1.18
+++ api.xml 20 Jul 2003 03:02:20 -0000 1.19
@@ -15,8 +15,13 @@
<p>Cocoon provides a JavaScript API to manage control flow based on an
<link
href="http://cvs.cocoondev.org/cgi-bin/viewcvs.cgi/?cvsroot=rhino";>extended</link>
version of <link href="http://www.mozilla.org/rhino";>Mozilla Rhino</link>
that supports continuations.</p>
+ <s2 title="Table of Contents">
+ <p><link href="#Java">Calling Java</link></p>
+ <p><link href="#FOM">Flow Object Model</link></p>
+ </s2>
+ <p/>
</s1>
- <s1 title="Calling Java from JavaScript">
+ <anchor id="Java"/><s1 title="Calling Java">
<p>
You can easily call any Java code from your Flowscripts, for example:
</p>
@@ -67,10 +72,11 @@
var d = new java.util.Date();
d.year = 2003; // same effect as d.setYear(2003);
</source>
+ <p/>
</s1>
- <s1 title="Flow Object Model">
- <p>Cocoon provides a set of system objects for use by Flowscripts. We call
this set of objects the Flow Object Model (<em>FOM</em>).
- The Flow Object Model contains following objects:</p>
+ <anchor id="FOM"/><s1 title="Flow Object Model">
+ <p>Cocoon provides a set of system objects for use by Flowscripts. We call
this set of objects the <em>Flow Object Model</em> (FOM).
+ The Flow Object Model consists of the following objects:</p>
<ul>
<li><link href="#cocoon">Cocoon</link></li>
<li><link href="#request">Request</link></li>
@@ -623,7 +629,7 @@
</s3>
</s2>
<s2 title="Log Object"><anchor id="log"/>
- <p> The <code>log</code> object provides an interface to the Cocoon logging
system.
+ <p> The <code>Log</code> object provides an interface to the Cocoon logging
system.
</p>
<p>
It supports the following functions:
@@ -702,6 +708,10 @@
<p>
<code>WebContinuation</code> objects support the following functions and
properties:
</p>
+ <s3 title="id">
+ <p><em>Property</em> <code>[String] id</code></p>
+ <p>Returns the unique string identifier of this continuation.</p>
+ </s3>
<s3 title="getParent">
<p>
<em>Function</em> <code>[WebContinuation] getParent()</code>
@@ -729,10 +739,6 @@
<code>WebContinuation</code> invalidates all the
<code>WebContinuation</code>s which are children of it.
</p>
- </s3>
- <s3 title="id">
- <p><em>Property</em> <code>[String] id</code></p>
- <p>Returns the unique string identifier of this continuation</p>
</s3>
</s2>
</s1>
1.5 +99 -36 cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxforms.xml
Index: jxforms.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxforms.xml,v
retrieving revision 1.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- jxforms.xml 14 Jul 2003 09:36:41 -0000 1.4
+++ jxforms.xml 20 Jul 2003 03:02:20 -0000 1.5
@@ -18,9 +18,9 @@
<s2 title="Table of Contents">
<p><link href="#Overview">Overview</link></p>
- <p><link href="#Sitemap">Sitemap</link></p>
<p><link href="#Controls">Form Controls</link></p>
<p><link href="#JSAPI">JavaScript API</link></p>
+ <p><link href="#Sitemap">Sitemap</link></p>
<p><link href="#Validation">Validation</link></p>
<p><link href="#HTML">Conversion to HTML</link></p>
</s2>
@@ -96,30 +96,6 @@
</p>
</s1>
- <s1 title="Sitemap"><anchor id="Sitemap"/>
-<p>To use JXForms, you will need to add several elements to your Cocoon <link
href="../concepts/sitemap.html">Sitemap</link>, namely the JXForms generator, and
several XSLT stylesheets. To use the JXForms generator, add a generator entry to your
Sitemap with the <code>src</code> attribute set to
<code>org.apache.cocoon.generation.JXFormsGenerator</code>, for example like this:</p>
-<source>
-<map:generators>
- <map:generator label="content,data"
- logger="sitemap.generator.jxforms" name="jxforms"
- src="org.apache.cocoon.generation.JXFormsGenerator"/>
-</map:generators>
- </source>
- <p>To invoke your form use the Sitemap's <code><map:call></code> operation
to invoke the <code>jxForm</code> Flowscript function, for example like this:</p>
-<source><![CDATA[
- <map:match pattern="feedBackWizard">
- <map:call function="jxForm">
- <map:parameter name="function" value="{1}"/>
- <map:parameter name="id" value="form-feedback"/>
- <map:parameter name="validator-schema-namespace"
value="http://www.ascc.net/xml/schematron"/>
- <map:parameter name="validator-schema"
value="schematron/wizard-xmlform-sch-report.xml"/>
- </map:call>
- </map:match>
-]]></source>
-
- <p>
- </p>
- </s1>
<s1 title="Form Controls"><anchor id="Controls"/>
<p>The JXForms tags are defined in the following namespace:</p>
<source>http://apache.org/cocoon/jxforms/1.0</source>
@@ -137,6 +113,7 @@
<xf:label>First Name</xf:label>
<xf:violations class="error"/>
</xf:input>
+ ...
</xf:form>
]]></source>
<p></p>
@@ -146,24 +123,54 @@
<li><code>view</code></li>
</ul>
<p>
- The <code>id</code> attribute must match the <code>id</code> Sitemap parameter
passed to the <code>jxForm</code> function in <code><map:call></code>. The
<code>view</code> attribute must match the <code>id</code> of a
<code><phase></code> element in your Schematron validation rules.
+ The <code>id</code> attribute must match the <code>id</code> Sitemap parameter
passed to the <link href="#jxForm">jxForm</link> function in <link
href="#Sitemap"><map:call></link>. The <code>view</code> attribute must match
the <code>id</code> of a <code><phase></code> element in your Schematron <link
href="#validation">validation</link> rules.
</p>
</s2>
<s2 title="error">
- <p>JXForms <code><error></code> has no counterpart in W3C XForms. If present
under the <code>form</code> element it serves as a placeholder for validation error
messages associated with the entire form.
+ <p>The JXForms <code><error></code> element has no counterpart in W3C
XForms. If present under the <code>form</code> element it serves as a placeholder for
validation error messages associated with the entire form.
</p>
</s2>
<s2 title="violations">
- <p>JXForms <code><violations></code> element has no counterpart in W3C
XForms.</p>
+ <p>The JXForms <code><violations></code> element has no counterpart in W3C
XForms. It is a placeholder used by the JXForms generator. For each validation error
that occur with respect to its containing element, the JXForms generator inserts a
<link href="violation">violation</link> element containing the validation error
message.</p>
<p>Example:</p>
<source><![CDATA[
+ <xf:input ref="/age">
+ <xf:label>Age</xf:label>
+ <xf:violations class="error"/>
+ </xf:input>
]]></source>
<p></p>
</s2>
- <s2 title="violation">
- <p>JXForms <code><violation></code> element has no counterpart in W3C
XForms.</p>
+ <anchor id="violation"/><s2 title="violation">
+ <p>The JXForms <code><violation></code> element has no counterpart in W3C
XForms. The JXForms generator inserts a <code>violation</code> element for each
validation error that occurs with respect to a <code>violations</code> element.</p>
<p>Example:</p>
+ <p>Assuming you had a Schematron validation rule such as:</p>
+ <source><![CDATA[
+<rule context="/age">
+ <assert test="number() > 0 and number(.) < 200">
+ Age should be a reasonably big positive number.
+ </assert>
+</rule>
+ ]]></source>
+ <p>
+ And a JXForms element such as:</p>
+ <source><![CDATA[
+ <xf:input ref="/age">
+ <xf:label>Age</xf:label>
+ <xf:violations class="error"/>
+ </xf:input>
+ ]]></source>
+ <p>
+ After executing the JXForms generator the element would be transformed into
the following:</p>
<source><![CDATA[
+ <xf:input ref="/age">
+ <xf:label>Age</xf:label>
+ <xf:violations class="error">
+ <xf:violation>
+Age should be a reasonably big positive number.
+ </xf:violation>
+ </xf:violations>
+ </xf:input>
]]></source>
<p></p>
</s2>
@@ -305,23 +312,34 @@
<p/>
</s2>
</s1>
- <s1 title="JavaScript API"><anchor id="JSAPI"/>
+<anchor id="JSAPI"/><s1 title="JavaScript API">
<p>
JXForms provides a JavaScript <code>JXForm</code> object that provides methods
for you to manage your form's <em>model</em> and to invoke its associated
<em>view</em> and any validation rules you've specified.
</p>
<p>
- To use JXForms in a Flowscript you must load
<code>resource://org/apache/cocoon/components/flow/javascript/JXForm.js</code> into
your script and define a function that takes one argument (the argument passed to your
function will be a JavaScript representation of your form), for example like this:</p>
+ To use JXForms in a Flowscript you must load</p><p>
<code>resource://org/apache/cocoon/components/flow/javascript/JXForm.js</code></p><p>into
your script and define a function that takes one argument to provide the form's page
flow (the argument passed to your function will be a JavaScript representation of your
form), for example like this:</p>
<source>
cocoon.load("resource://org/apache/cocoon/components/flow/javascript/JXForm.js");
function myFormHandler(form) {
+ form.setModel(...);
+ form.sendView("page1.xml");
...
}
</source>
<p>
</p>
- <s2 title="JXForm Object">
+ <anchor id="jxForm"/><s2 title="jxForm">
+ <p>
+ The entry point from the Cocoon <link href="#Sitemap">Sitemap</link> to your
form is the <code>jxForm</code> function:
+ </p>
+ <p>
+ <em>Function</em> <code>jxForm([String] functionName, [String] id, [String]
validationSchema, [String] validationDocument)</code>
+ </p>
+ <p>
+ This function creates a new <code>JXForm</code> object with the provided
<code>id</code>, <code>validationSchema</code>, and <code>validationDocument</code>,
and then invokes the function identified by <code>functionName</code> to process the
form, passing the newly created <code>JXForm</code> object as the argument to the
function. Currently, the only supported validation schema is <link
href="http://www.ascc.net/xml/resource/schematron/Schematron2000.html";>Schematron</link>
which is identified by the namespace <code>http://www.ascc.net/xml/schematron</code>.
The <code>validationDocument</code> if provided, should be a url that can be resolved
by the Cocoon source resolver.
+ </p>
<p>
The <code>JXForm</code> object passed to your function has the following
properties and functions:</p>
<s3 title = "setModel"><anchor id="setModel"/>
@@ -380,18 +398,63 @@
<p>
<em>Function</em> <code>finish([String] uri)</code>
</p>
- <p>Forwards to <code>uri</code> and then releases all resources associated
with this form.</p>
+ <p>Forwards to <code>uri</code> (if provided) and then releases all resources
associated with this form.</p>
</s3>
</s2>
</s1>
+ <anchor id="Sitemap"/><s1 title="Sitemap">
+<p>To use JXForms, you will need to add several elements to your Cocoon <link
href="../concepts/sitemap.html">Sitemap</link>, namely the JXForms generator, and
several XSLT stylesheets. To use the JXForms generator, add a generator entry to your
Sitemap with the <code>src</code> attribute set to
<code>org.apache.cocoon.generation.JXFormsGenerator</code>, for example like this:</p>
+<source>
+<map:generators>
+ <map:generator label="content,data"
+ logger="sitemap.generator.jxforms" name="jxforms"
+ src="org.apache.cocoon.generation.JXFormsGenerator"/>
+</map:generators>
+ </source>
+ <p>To invoke your form use the Sitemap's <link
href="sitemap.html#call"><map:call></link> operation to invoke the
<code>jxForm</code> Flowscript function, for example like this:</p>
+<source><![CDATA[
+ <map:match pattern="feedBackWizard">
+ <map:call function="jxForm">
+ <map:parameter name="function" value="{1}"/>
+ <map:parameter name="id" value="form-feedback"/>
+ <map:parameter name="validator-schema-namespace"
+ value="http://www.ascc.net/xml/schematron"/>
+ <map:parameter name="validator-schema"
+ value="schematron/wizard-xmlform-sch-report.xml"/>
+ </map:call>
+ </map:match>
+]]></source>
+
+ <p>
+ </p>
+ </s1>
<s1 title="Validation"><anchor id="Validation"/>
<p>
JXForms provides declarative form validation using the <link
href="http://www.ascc.net/xml/resource/schematron/Schematron2000.html";>Schematron</link>
assertion language. Since Schematron is also based on XPath, you use the same
expressions to reference your model in your validation rules as in your forms. In
addition, because JXForms implements Schematron using <link
href="http://jakarta.apache.org/commons/jxpath";>JXPath</link>, you can make assertions
about Java and JavaScript objects in your validation rules as well as about XML
documents.
</p>
</s1>
<s1 title="Conversion to HTML"><anchor id="HTML"/>
- <p>For conversion of JXForms controls to XHTML, JXForms provides two XSLT
stylesheets that must be applied to the output of JXFormsGenerator:
<code>jxforms-default.xsl</code> and <code>jxforms2html.xsl</code>. The former
performs formatting of validation error messages. The latter converts the result to
XHTML.
- </p>
+ <p>For conversion of JXForms controls to XHTML, JXForms provides two XSLT
stylesheets that must be applied to the output of JXFormsGenerator:
<code>jxforms-default.xsl</code> and <code>jxforms2html.xsl</code>. The former
performs formatting of validation error messages. The latter converts the result to
XHTML.</p>
+ <p>A typical JXForms pipeline would look like this:</p>
+<source><![CDATA[
+ <map:match pattern="view/*.xml">
+ <!-- original JXForms document -->
+ <map:generate type="jxforms" src="view/{1}.xml"/>
+
+ <!-- Personalize the look and feel of the form controls -->
+ <map:transform type="xslt" src="stylesheets/mystyle.xsl" />
+
+ <!-- Transform the JXForms controls to HTML controls -->
+
+ <map:transform type="xslt" src="stylesheets/jxforms-default.xsl" />
+
+ <map:transform type="xslt" src="stylesheets/jxforms2html.xsl" />
+
+ <!-- sending the HTML back to the browser -->
+ <map:serialize type="html"/>
+ </map:match>
+]]></source>
+ <p/>
</s1>
</body>
</document>
1.15 +3 -2 cocoon-2.1/src/documentation/xdocs/userdocs/flow/sitemap.xml
Index: sitemap.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/sitemap.xml,v
retrieving revision 1.14
retrieving revision 1.15
diff -u -r1.14 -r1.15
--- sitemap.xml 13 Jul 2003 19:53:14 -0000 1.14
+++ sitemap.xml 20 Jul 2003 03:02:20 -0000 1.15
@@ -27,7 +27,8 @@
</map:flow>
]]></source>
</s2>
- <s2 title="call">
+ <p/>
+ <anchor id="call"/><s2 title="call">
<p>The <code>call</code> element allows you to call a top-level function in
your Flowscript or to invoke an existing continuation.</p>
<s3 title="function"><anchor id="callFunction"/>
<p>If the <code>function</code> attribute is present, then the Sitemap will
invoke a top-level function defined in your Flowscript. The <code>function</code>
attribute specifies the name of the function. Zero or more nested
<code>parameter</code> elements may be provided to pass arguments to the function.</p>
@@ -56,6 +57,7 @@
sendPage("private/index.html", {param: param});
}
]]></source>
+ <p/>
</s3>
<s3 title="continuation"><anchor id="callContinuation"/>
<p>If the <code>continuation</code> attribute is present, then the Sitemap
will invoke an existing continuation of your Flowscript. The <code>continuation</code>
attribute specifies the unique id of the continuation.</p>
@@ -71,7 +73,6 @@
</s3>
</s2>
</s1>
-
</body>
</document>
1.17 +2 -2 cocoon-2.1/src/documentation/xdocs/userdocs/flow/velocity.xml
Index: velocity.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/velocity.xml,v
retrieving revision 1.16
retrieving revision 1.17
diff -u -r1.16 -r1.17
--- velocity.xml 14 Jul 2003 01:00:15 -0000 1.16
+++ velocity.xml 20 Jul 2003 03:02:20 -0000 1.17
@@ -14,8 +14,8 @@
<link href="http://jakarta.apache.org/velocity";>Velocity</link>
<link href="../generators/velocity-generator.html">Generator</link>
provides access to the immediate properties of the context object passed to
- <link href="api.html#sendPage"><code>sendPage</code></link> and
- <link href="api.html#sendPageAndWait"><code>sendPageAndWait</code></link>. In
addition,
+ <link href="api.html#sendPage"><code>cocoon.sendPage</code></link> and
+ <link
href="api.html#sendPageAndWait"><code>cocoon.sendPageAndWait</code></link>. In
addition,
the current <link
href="api.html#WebContinuation"><code>WebContinuation</code></link>
is also available as a variable named <code>$continuation</code>. You would
typically access
its <code>id</code>:</p>
