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.
