You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@cocoon.apache.org by co...@apache.org on 2003/07/20 05:02:20 UTC
cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/flow api.xml jxforms.xml sitemap.xml velocity.xml
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>