Google Git
Sign in
apache / cocoon / bfc07eab6bcd4f51f6d0efa239a16bbd8bdfa06e / . / ASF_20_SRC_AUTO / src / documentation / xdocs / userdocs / flow / jxforms.xml
blob: 8041c96580c94f81e7020d1ea89836f7696348da [file] [log] [blame]
<?xml version='1.0' encoding='ISO-8859-1'?>
<!DOCTYPE document PUBLIC "-//APACHE//DTD Documentation V1.0//EN" "document-v10.dtd">
<document>
<header>
<title>JXForms</title>
<authors>
<person name="Christopher Oliver" email="coliver@apache.org" />
</authors>
</header>
<body>
<s1 title="JXForms">
<p>
<em>JX</em>Forms is a framework that uses Apache
<link href="http://jakarta.apache.org/commons/jxpath"><em>JX</em>Path</link>
to support <link href="http://www.w3.org/MarkUp/Forms/">W3C XForms</link>-based
markup and automated server-side binding to
<link href="http://java.sun.com/products/javabeans/">JavaBeans</link>,
<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><link href="#Overview">Overview</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>
</s1>
<anchor id="Overview"/><s1 title="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
on the controls (note that we have
intentionally defaulted the JXForms namespace prefix here):</p>
<source>
&lt;select1 ref="/method"&gt;
&lt;label&gt;Select Payment Method&lt;/label&gt;
&lt;item&gt;
&lt;label&gt;Cash&lt;/label&gt;
&lt;value&gt;cash&lt;/value&gt;
&lt;/item&gt;
&lt;item&gt;
&lt;label&gt;Credit&lt;/label&gt;
&lt;value&gt;cc&lt;/value&gt;
&lt;/item&gt;
&lt;/select1&gt;
&lt;input ref="/number"&gt;
&lt;label&gt;Credit Card Number&lt;/label&gt;
&lt;/input&gt;
&lt;input ref="/expiry"&gt;
&lt;label&gt;Expiration Date&lt;/label&gt;
&lt;/input&gt;
&lt;submit id="submit" continuation="forward"&gt;
&lt;label&gt;Submit&lt;/label&gt;
&lt;/submit&gt;</source>
<p>
In your Flow script you would supply an appropriate model, for example, like this:</p>
<source>
var model = {
method: "cash",
number: "",
expiry: ""
}
</source>
<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>
<source>
var model = {
method: "cash",
number: "",
expiry: ""
}
form.setModel(model);
form.sendView("form.xml"); // like sendPageAndWait this call blocks
// until the form is submitted
// process the form's values:
if (model.method == "cash") {
...
} else if (model.method == "cc") {
....
}
</source>
<p>
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>
<anchor id="Controls"/><s1 title="Form 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>
<anchor id="form"/><s2 title="form">
<p>The JXForms <code>&lt;form&gt;</code> element represents one page of 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[
<form id="form-feedback" view="userIdentity" action="">
<label>Personal Information</label>
<error>
<violations class="error"/>
</error>
<input ref="/firstName">
<label>First Name</label>
<violations class="error"/>
</input>
...
</form>
]]></source>
<p></p>
<p>It supports the following attributes:</p>
<ul>
<li><code>id</code></li>
<li><code>view</code></li>
<li><code>action</code></li>
</ul>
<p>
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">&lt;map:call&gt;</link>. The <code>view</code> attribute must match the <code>id</code> of a <code>&lt;phase&gt;</code> element in your Schematron <link href="#validation">validation</link> rules. For HTML forms the <code>action</code> attribute specifies the relative URI to which the form will be submitted.
</p>
</s2>
<anchor id="label"/><s2 title="label">
<p>JXForms <code>&lt;label&gt;</code> element is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-commonelems-label">label</link> element. This required element labels the containing form control with a descriptive label.</p>
<p>Example:</p>
<source><![CDATA[
<input ref="/firstName">
<label>First Name</label>
</input>
]]></source>
<p></p>
</s2>
<s2 title="help">
<p>JXForms <code>&lt;help&gt;</code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-commonelems-help">help</link> element. The optional element <code>help</code> provides a convenient way to attach help information to a form control. </p>
<p>Example:</p>
<source><![CDATA[
<input ref="/email">
<label>Email</label>
<help>Please check this carefully</help>
</input>
]]></source>
<p></p>
</s2>
<s2 title="hint">
<p>JXForms <code>&lt;hint&gt;</code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-commonelems-hint">hint</link> element.The optional element <code>hint</code> provides a convenient way to attach hint information to a form control.</p>
<p>Example:</p>
<source><![CDATA[
<submit id="next" phase="userIdentity" continuation="forward" class="button">
<label>Next</label>
<hint>Go to next page</hint>
</submit>
]]></source>
<p></p>
</s2>
<anchor id="value"/><s2 title="value">
<p>JXForms <code>&lt;value&gt;</code> element is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-common-choices-value">value</link> element. This element provides a storage value to be used when an item is selected.</p>
<p>Example:</p>
<source><![CDATA[
<select1 ref="/option">
<label>You only have one option</label>
<item>
<label>Your only option</label>
<value>Some value</value>
</item>
</select1>
]]></source>
<p></p>
</s2>
<anchor id="item"/><s2 title="item">
<p>JXForms <code>&lt;item&gt;</code> element is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-common-elements-item">item</link> element. This element specifies the storage <link href="#value">value</link> and <link href="#label">label</link> to represent an item in a list. It is found within elements <link href="#select1">select1</link> and <link href="#select">select</link>.</p>
<p>Example:</p>
<source><![CDATA[
<select1 ref="/option">
<label>You have two options</label>
<item>
<label>Your first option</label>
<value>Some value</value>
</item>
<item>
<label>Your second option</label>
<value>Another value</value>
</item>
</select1>
]]></source>
<p></p>
</s2>
<s2 title="violations">
<p>The JXForms <code>&lt;violations&gt;</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"><code>violation</code></link> element containing the validation error message.</p>
<p>Example:</p>
<source><![CDATA[
<input ref="/age">
<label>Age</label>
<violations class="error"/>
</input>
]]></source>
<p></p>
</s2>
<anchor id="violation"/><s2 title="violation">
<p>The JXForms <code>&lt;violation&gt;</code> element has no counterpart in W3C XForms. The JXForms generator inserts a <code>violation</code> element for each validation error that occurs into the corresponding <code>&lt;violations&gt;</code> element of a form control.</p>
<p>Example:</p>
<p>Assuming you had a Schematron validation rule such as:</p>
<source><![CDATA[
<rule context="/age">
<assert test="number() &gt; 0 and number(.) &lt; 200">
Age should be a reasonably big positive number.
</assert>
</rule>
]]></source>
<p>
And a JXForms element such as:</p>
<source><![CDATA[
<input ref="/age">
<label>Age</label>
<violations class="error"/>
</input>
]]></source>
<p>
After executing the JXForms generator the element would be transformed into the following:</p>
<source><![CDATA[
<input ref="/age">
<label>Age</label>
<violations class="error">
<violation>
Age should be a reasonably big positive number.
</violation>
</violations>
</input>
]]></source>
<p></p>
</s2>
<s2 title="input">
<p>JXForms <code>&lt;input&gt;</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[
<input ref="order/shipTo/street" class="streetAddress">
<label>Street</label>
<hint>Please enter the number and street name</hint>
</input>
]]></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>&lt;secret&gt;</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[
<secret ref="/login/password">
<label>Password</label>
<hint>The password you enter will not be displayed.</hint>
</secret>
]]></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>&lt;textarea&gt;</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[
<textarea ref="message/body" class="messageBody">
<label>Message Body</label>
<hint>Enter the text of your message here</hint>
</textarea>
]]></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>JXForms <code>&lt;output&gt;</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[
I charged you -
<output ref="order/totalPrice"/>
- and here is why
]]></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>
<anchor id="select"/><s2 title="select">
<p>
</p>
<p>JXForms <code>&lt;select&gt;</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[
<select ref="my:flavors">
<label>Flavors</label>
<choices>
<item>
<label>Vanilla</label>
<value>v</value>
</item>
<item>
<label>Strawberry</label>
<value>s</value>
</item>
<item>
<label>Chocolate</label>
<value>c</value>
</item>
</choices>
</select>
]]></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>
</s2>
<anchor id="select1"/><s2 title="select1">
<p>JXForms <code>&lt;select1&gt;</code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice8.html#ui-selectOne">select1</link> element.
This form control allows the user to make a single selection from multiple choices. It supports the following attributes:</p>
<ul>
<li><code>ref</code></li>
<li><code>appearance</code></li>
<li><code>class</code></li>
</ul>
<p>Example:</p>
<source><![CDATA[
<select1 ref="my:flavor">
<label>Flavor</label>
<item>
<label>Vanilla</label>
<value>v</value>
</item>
<item>
<label>Strawberry</label>
<value>s</value>
</item>
<item>
<label>Chocolate</label>
<value>c</value>
</item>
</select1>
]]></source>
<p></p>
<p/>
</s2>
<s2 title="submit">
<p>JXForms <code>&lt;submit&gt;</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[
<submit id="timecard" continuation="forward">
<label>Submit Timecard</label>
</submit>
<submit id="prev" continuation="back">
<label>Go Back</label>
</submit>
]]></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>
The required <code>id</code> attribute specifies the unique id of this <code>submit</code> element. This value is returned by the <link href="#getSubmitId">getSubmitId</link> function when this element is used to submit a form. The optional <code>continuation</code> attribute provides support for automated back/forward navigation in multipage forms. A value of <code>forward</code> (the default) causes the form to be submitted normally. A value of <code>back</code> causes the previous page of the form to be displayed.
</p>
</s2>
<s2 title="group">
<p>JXForms <code>&lt;group&gt;</code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice9.html#ui-group">group</link> element. It is used as a container for defining a hierarchy of form controls. Groups can be nested to create complex hierarchies.</p>
<p>Example:</p>
<source><![CDATA[
<group ref="address">
<label>Shipping Address</label>
<input ref="line_1">
<label>Address line 1</label>
</input>
<input ref="line_2">
<label>Address line 2</label>
</input>
<input ref="postcode">
<label>Postcode</label>
</input>
</group>
]]></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>&lt;group&gt;</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>&lt;repeat&gt;</code> is based on the W3C XForms <link href="http://www.w3.org/TR/xforms/slice9.html#ui-repeat">repeat</link> element. The repeat element iterates over the collection of objects defined by its <code>nodeset</code> attribute.</p>
<p>Example:</p>
<source><![CDATA[
<xf:repeat nodeset="/cartItems">
<tr bgcolor="#FFFF88">
<td>
<b>
<xf:output ref="./itemId"/>
</b>
</td>
</tr>
</xf:repeat>
]]></source>
<p></p>
<p> It supports the following attributes:</p>
<ul>
<li><code>nodeset</code></li>
</ul>
<p/>
<p>
</p>
</s2>
<s2 title="itemset">
<p>JXForms <code>&lt;itemset&gt;</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[
<select ref="/order">
<label>Flavors</label>
<itemset nodeset="/flavors/flavor">
<label ref="/description"/>
<value ref="/description"/>
</itemset>
</select>
]]></source>
<p></p>
<p> It supports the following attributes:</p>
<ul>
<li><code>nodeset</code></li>
</ul>
<p/>
</s2>
</s1>
<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</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>
<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"/>
<p>
<em>Function</em> <code>setModel([Object] model)</code>
</p>
<p>Set the model object of this form. <code>model</code> may be any Java bean, JavaScript, DOM, or JDOM object.</p>
</s3>
<s3 title = "getModel"><anchor id="getModel"/>
<p>
<em>Function</em> <code>[Object] getModel()</code>
</p>
<p>Get the model object of this form.</p>
</s3>
<s3 title = "sendView"><anchor id="sendView"/>
<p>
<em>Function</em> <code>sendView([String] uri, [Function] validator)</code>
</p>
<p>
Sends view to presentation pipeline and waits for subsequent submission.
Automatically resends view if validation fails.
Creates two continuations: one immediately before the page is sent
and one immediately after. These are used to implement automated support
for back/forward navigation in the form. When you move forward in the
form the second continuation is invoked. When you move back from the
following page the first continuation is invoked.
</p>
</s3>
<s3 title = "addViolation"><anchor id="addViolation"/>
<p>
<em>Function</em> <code>addViolation([String] xpath, [String] message)</code>
</p>
<p>Adds a violation to this form</p>
</s3>
<s3 title = "hasViolations"><anchor id="hasViolations"/>
<p>
<em>Function</em> <code>[Boolean] hasViolations()</code>
</p>
<p>Does this form have violations?</p>
</s3>
<s3 title = "getValue"><anchor id="getValue"/>
<p>
<em>Function</em> <code>[Object] getValue([String] xpath)</code>
</p>
<p>Computes the value of an xpath expression against the model of this form</p>
</s3>
<s3 title = "iterate"><anchor id="iterate"/>
<p>
<em>Function</em> <code>[java.util.Iterator] iterate([String] xpath)</code>
</p>
<p>Returns an iterator over a nodeset value of an xpath expression evaluated
against the model of this form</p>
</s3>
<s3 title = "getSubmitId"><anchor id="getSubmitId"/>
<p>
<em>Function</em> <code>[String] getSubmitId()</code>
</p>
<p>Get the id of the submit element used to submit this form.</p>
</s3>
<s3 title = "finish"><anchor id="finish"/>
<p>
<em>Function</em> <code>finish([String] uri)</code>
</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>
&lt;map:generators&gt;
&lt;map:generator label="content,data"
logger="sitemap.generator.jxforms" name="jxforms"
src="org.apache.cocoon.generation.JXFormsGenerator"/&gt;
&lt;/map:generators&gt;
</source>
<p>To invoke your form use the Sitemap's <link href="sitemap.html#call">&lt;map:call&gt;</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>
The required <code>function</code> parameter specifies the name of a JavaScript function that will provide the page flow for your form. The required <code>id</code> attribute must match the value of the <code>id</code> attribute of the <link href="#form">form</link> element of your form. The optional <code>validator-schema-namespace</code> and <code>validator-schema</code> parameters identify the the schema namespace and instance document of your validation rules, if provided. Currently, only the <link href="#Validation">Schematron</link> assertion language is supported.
</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>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>