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/14 03:00:16 UTC
cvs commit: cocoon-2.1/src/documentation/xdocs/userdocs/flow jxforms.xml jxtemplate.xml velocity.xml woody.xml
coliver 2003/07/13 18:00:16
Modified: src/documentation/xdocs/userdocs/flow jxforms.xml
jxtemplate.xml velocity.xml woody.xml
Log:
More docs (still incomplete though)
Revision Changes Path
1.3 +197 -51 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.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- jxforms.xml 13 Jul 2003 19:53:14 -0000 1.2
+++ jxforms.xml 14 Jul 2003 01:00:15 -0000 1.3
@@ -14,8 +14,19 @@
<link href="http://www.w3.org/DOM/">XML/DOM</link>,
<link href="http://www.jdom.org/">JDOM</link>,
<link href="http://jakarta.apache.org/commons/beanutils/api/org/apache/commons/beanutils/DynaBean.html">DynaBeans</link>, and JavaScript objects.
+ </p>
- </p>
+ <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="#Validation">Validation</link></p>
+ <p><link href="#HTML">Conversion to HTML</link></p>
+ </s2>
+ </s1>
+ <s1 title="Overview"><anchor id="Overview"/>
+
<p>W3C XForms defines a device-neutral, platform-independent set of
form controls suitable for general-purpose use. JXForms supports a subset of these controls. The controls are
bound to a <em>model</em> provided by your Flowscript via <link href="http://www.w3.org/TR/xpath">XPath</link> expressions, for example in this simple case using the <code>ref</code> attribute
@@ -44,11 +55,11 @@
<label>Expiration Date</label>
</input>
-<submit submission="submit">
+<submit id="submit" continuation="forward">
<label>Submit</label>
</submit></source>
<p>
- In your Flowscript you would supply an appropriate model, for example, like this:</p>
+ In your Flow script you would supply an appropriate model, for example, like this:</p>
<p><source>
var model = {
method: "cash",
@@ -56,8 +67,12 @@
expiry: ""
}
</source></p>
- <p>
- Upon submission of the form the model will be updated accordingly, and you can take action in your script based on its values:
+ <p>
+ Since JXForms uses <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link>, your model may consist of any objects that <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link> supports.
+ </p>
+ <p>
+ Use the <code>setModel()</code> function of the form to associate your model with the form. Then use the <code>sendView()</code> function of the form to display it.
+ Upon submission of the form, the model will be automatically updated and you can take action in your script based on its values:
</p>
<p><source>
var model = {
@@ -76,101 +91,226 @@
....
}
</source></p>
- <p>
- Since JXForms uses <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link>, your model may consist of any objects that <link href="http://jakarta.apache.org/commons/jxpath">JXPath</link> supports.
- </p>
<p>
- JXForms also supports declarative validation of form elements using Schematron, and automated support for back/forward navigation in multi-page forms using continuations.
+ JXForms also supports declarative <link href="#validation">validation</link> of form elements using Schematron, and automated <link href="#backNext">support</link> for back/forward navigation in multi-page forms using continuations.
</p>
</s1>
- <s1 title="Form Controls">
+ <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>
<p>JXForms supports the following controls:</p>
<s2 title="form">
- <p/>
+ <p>The JXForms <code><form></code> element represents the overall form. It also corresponds to a validation <em>phase</em> in your <link href="#Validation">validation</link> rules. It has no direct counterpart in W3C XForms.</p>
+ <p>Example:</p>
+ <source><![CDATA[
+ <xf:form id="form-feedback" view="userIdentity">
+ <xf:label>Personal Information</xf:label>
+ <error>
+ <xf:violations class="error"/>
+ </error>
+ <xf:input ref="/firstName">
+ <xf:label>First Name</xf:label>
+ <xf:violations class="error"/>
+ </xf:input>
+ </xf:form>
+ ]]></source>
+ <p></p>
+ <p>It supports the following attributes:</p>
+ <ul>
+ <li><code>id</code></li>
+ <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.
+ </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>
+ </s2>
+ <s2 title="violations">
+ <p>JXForms <code><violations></code> element has no counterpart in W3C XForms.</p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+ </s2>
+ <s2 title="violation">
+ <p>JXForms <code><violation></code> element has no counterpart in W3C XForms.</p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
</s2>
<s2 title="input">
+ <p>JXForms <code><input></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-input">input</link> element. It allows the user to do free-form data entry.</p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+ <p>It supports the following attributes:</p>
+ <ul>
+ <li><code>ref</code></li>
+ <li><code>appearance</code></li>
+ <li><code>class</code></li>
+ </ul>
<p/>
</s2>
<s2 title="secret">
+ <p>JXForms <code><secret></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-secret">secret</link> element. It is is used for entering information that is considered sensitive, and thus not echoed to a visual or aural display as it is being entered, e.g., password entry. </p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+<p>It supports the following attributes:</p>
+
+ <ul>
+ <li><code>ref</code></li>
+ <li><code>appearance</code></li>
+ <li><code>class</code></li>
+ </ul>
<p/>
</s2>
<s2 title="textarea">
+ <p>JXForms <code><textarea></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-textarea">textarea</link> element. </p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+ <p>It supports the following attributes:</p>
+ <ul>
+ <li><code>ref</code></li>
+ <li><code>appearance</code></li>
+ </ul>
<p/>
</s2>
<s2 title="output">
- <p/>
+ <p>JXForms <code><output></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-output">output</link> element. It is used to display values from the model, but provides no means to enter or modify those values.</p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+ <p>It supports the following attributes:</p>
+ <ul>
+ <li><code>ref</code></li>
+ <li><code>value</code></li>
+ <li><code>appearance</code></li>
+ <li><code>class</code></li>
+ </ul>
</s2>
<s2 title="select">
<p>
</p>
- <p>JXForms <code><select></code> is modelled after the <link href="http://www.w3.org/TR/xforms/slice8.html#ui-selectMany">W3C XForms <select></link> element. It supports the following attributes:</p>
+ <p>JXForms <code><select></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-selectMany">select</link> element. </p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+
+<p>It supports the following attributes:</p>
<ul>
<li><code>ref</code></li>
- <li><code>id</code></li>
<li><code>appearance</code></li>
+ <li><code>class</code></li>
</ul>
</s2>
<s2 title="select1">
+ <p>JXForms <code><select></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-selectOne">select1</link> element. It supports the following attributes:</p>
+ <ul>
+ <li><code>ref</code></li>
+ <li><code>appearance</code></li>
+ <li><code>class</code></li>
+ </ul>
<p/>
</s2>
<s2 title="submit">
- <p>JXForms <code><submit></code> differs from that of W3C XForms. It supports the following attributes:</p>
+ <p>JXForms <code><submit></code> differs from <link href="http://www.w3.org/TR/xforms/slice8.html#ui-submit">that</link> of W3C XForms. </p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+
+<p>It supports the following attributes:</p>
<ul>
<li><code>id</code></li>
<li><code>continuation</code></li>
<li><code>class</code></li>
</ul>
- <p>Example: Submit
- </p>
-<source>
-<submit submission="timecard">
- <label>Submit Timecard</label>
-</submit>
-</source>
<p>
</p>
</s2>
<s2 title="group">
- <p/>
+ <p>JXForms <code><group></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice9.html#ui-group">group</link> element.</p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+
+ <p>It supports the following attributes:</p>
+ <ul>
+ <li><code>ref</code></li>
+ <li><code>class</code></li>
+ </ul>
+ <p>
+ The value of the <code>ref</code> attribute of a <code><group></code> is the context node for evaluting relative paths of the <code>ref</code> attributes of its sub-elements.
+ </p>
</s2>
<s2 title="repeat">
+ <p>JXForms <code><repeat></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice9.html#ui-repeat">repeat</link> element.</p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+<p> It supports the following attributes:</p>
+ <ul>
+ <li><code>nodeset</code></li>
+ </ul>
<p/>
</s2>
<s2 title="itemset">
+ <p>JXForms <code><itemset></code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice9.html#ui-common-elements-itemset">itemset</link> element. It is used for the dynamic creation of selections within the <code>select</code> and <code>select1</code> elements.</p>
+ <p>Example:</p>
+ <source><![CDATA[
+ ]]></source>
+ <p></p>
+<p> It supports the following attributes:</p>
+ <ul>
+ <li><code>nodeset</code></li>
+ </ul>
<p/>
</s2>
</s1>
- <s1 title="Sitemap">
-<p>To use the JXForms, you will need to add several elements to your <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 you 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>
-
-</s1>
- <s1 title="Flowscript">
+ <s1 title="JavaScript API"><anchor id="JSAPI"/>
<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 you've specified.
+ 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>JXForm.js</code> into your script and define a function that takes at 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 <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>
<source>
cocoon.load("resource://org/apache/cocoon/components/flow/javascript/JXForm.js");
@@ -178,8 +318,9 @@
function myFormHandler(form) {
...
}
-
</source>
+ <p>
+ </p>
<s2 title="JXForm Object">
<p>
The <code>JXForm</code> object passed to your function has the following properties and functions:</p>
@@ -243,9 +384,14 @@
</s3>
</s2>
</s1>
- <s1 title="Validation">
+ <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="Stylesheets">
+ <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>
</s1>
</body>
</document>
1.16 +3 -3 cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxtemplate.xml
Index: jxtemplate.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/jxtemplate.xml,v
retrieving revision 1.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- jxtemplate.xml 13 Jul 2003 19:53:14 -0000 1.15
+++ jxtemplate.xml 14 Jul 2003 01:00:15 -0000 1.16
@@ -70,13 +70,13 @@
<source>
<form action="${continuation.id}">
</source>
-<p>You can also reach previous continuations by using the <code>getContinuation()</code> function:</p>
+<p>You can also reach previous continuations by using the <code>getParent()</code> function:</p>
<source>
- <form action="${continuation.getContinuation(1).id}" >
+ <form action="${continuation.getParent().id}" >
</source>
<p>or using an XPath expression:</p>
<source>
- <form action="#{getContinuation($continuation, 1)/id}" >
+ <form action="#{getParent($continuation)/id}" >
</source>
</s1>
<s1 title ="Tags">
1.16 +6 -6 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.15
retrieving revision 1.16
diff -u -r1.15 -r1.16
--- velocity.xml 13 Jul 2003 19:53:14 -0000 1.15
+++ velocity.xml 14 Jul 2003 01:00:15 -0000 1.16
@@ -22,19 +22,19 @@
<source>
<form action="$continuation.id">
</source>
- <p>You can also reach previous continuations by using the <code>getContinuation()</code> function:</p>
+ <p>You can also reach previous continuations by using the <code>getParent()</code> function:</p>
<source>
- <form action="$continuation.getContinuation(1).id" >
+ <form action="$continuation.getParent().id" >
</source>
<p>In addition the following implicit objects are always available in the Velocity context:</p>
<dl>
- <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Request.html">org.apache.cocoon.environment.Request</link> <code>$request</code> </dt>
+ <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Request.html">Request</link> <code>$request</code> </dt>
<dd>The current Cocoon request</dd>
- <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Response.html">org.apache.cocoon.environment.Response</link> <code>$response</code> </dt>
+ <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Response.html">Response</link> <code>$response</code> </dt>
<dd>The Cocoon response associated with the current request</dd>
- <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Session.html">org.apache.cocoon.environment.Session</link> <code>$session</code> </dt>
+ <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Session.html">Session</link> <code>$session</code> </dt>
<dd>The Cocoon session associated with the current request</dd>
- <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Context.html">org.apache.cocoon.environment.Context</link> <code>$context</code> </dt>
+ <dt><link href="../../apidocs/java/org/apache/cocoon/environment/Context.html">Context</link> <code>$context</code> </dt>
<dd>The Cocoon context associated with the current request</dd>
<dt><code>org.apache.avalon.framework.parameters.Parameters</code> <code>$parameters</code> </dt>
<dd>Any parameters passed to the generator in the pipeline</dd>
1.2 +5 -10 cocoon-2.1/src/documentation/xdocs/userdocs/flow/woody.xml
Index: woody.xml
===================================================================
RCS file: /home/cvs/cocoon-2.1/src/documentation/xdocs/userdocs/flow/woody.xml,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- woody.xml 13 Jul 2003 00:48:29 -0000 1.1
+++ woody.xml 14 Jul 2003 01:00:15 -0000 1.2
@@ -56,6 +56,8 @@
}
]]></source>
+ <p>
+ </p>
<s2 title ="The woody function"><anchor id="woody"/>
<p>The entry point to a Woody form is the <code>woody()</code> function:
<p>
@@ -82,16 +84,9 @@
parameter, the newly created form.
</p>
<p>
- To use Woody in a Flowscript you must load <code>woody.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 Woody form), for example like this:</p>
- <source>
-
- cocoon.load("resource://org/apache/cocoon/components/woody/flow/javascript/woody.js");
-
- function myFormHandler(form) {
- ...
- }
- </source>
- </s2>
+ To use Woody in a Flowscript you must load <code>woody.js</code> into your script and define a function that takes one argument (<code>form1</code> in the example at the top of this page). The argument passed to your function will be a JavaScript representation of your Woody form.
+ </p>
+ </s2>
<s2 title="Form Object">
<p>
Woody provides a JavaScript <code>Form</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 you've specified.