A document has been updated:
http://cocoon.zones.apache.org/daisy/documentation/478.html
Document ID: 478
Branch: main
Language: default
Name: Cocoon Forms: A Simple Example (unchanged)
Document Type: Document (unchanged)
Updated on: 10/19/05 6:50:23 PM
Updated by: Bruno Dumon
A new version has been created, state: publish
Parts
=====
Content
-------
This part has been updated.
Mime type: text/xml (unchanged)
File name: (unchanged)
Size: 12198 bytes (previous version: 10430 bytes)
Content diff:
(7 equal lines skipped)
<ol>
<li>Create a form definition file</li>
--- <li>Create a template file for the Forms Template Transformer</li>
+++ <li>Create a template file</li>
<li>Write a bit of flowscript</li>
<li>Add some pipelines to the sitemap</li>
</ol>
+++ <p>You can try this sample out on a default Cocoon install. In the webapp
+++ directory (build/webapp), create a new subdirectory, for example called
+++ <tt>myformtest</tt>. In there, create the files as outlined in this
sample.</p>
+++
<p>Here is a screenshot of the form we're going to create:</p>
<p align="center"><img src="daisy:350"/></p>
<h1>Create a form definition file</h1>
--- <p>Below the form definition file is displayed. This lists all the widgets
in
--- the form, together with their configuration information.</p>
+++ <p>Below the form definition file is displayed,
+++ <tt>registration_definition.xml</tt>. This lists all the widgets in the
form,
+++ together with their configuration information.</p>
<pre><fd:form
xmlns:fd="http://apache.org/cocoon/forms/1.0#definition">
(51 equal lines skipped)
<p>All elements are in the Forms Definition namespace:
<strong>fd</strong>.</p>
--- <p>Every definition file has a <strong><fd:form></strong> element as
the
--- root element.</p>
+++ <p>Every definition file has a <tt><fd:form></tt> element as the root
+++ element.</p>
<p>The child widgets of the form are defined inside the
--- <strong><fd:widgets></strong> element. As you can see, most of the
widgets
--- are field widgets. The field widget is the most important widget in CForms.
It
--- is very flexible because it can be associated with different datatypes and
with
--- a selection list. See the reference docs for more information on this and
other
+++ <tt><fd:widgets></tt> element. As you can see, most of the widgets are
+++ field widgets. The field widget is the most important widget in CForms. It
is
+++ very flexible because it can be associated with different datatypes and
with a
+++ selection list. See the reference docs for more information on this and
other
widgets.</p>
--- <p>A nice feature is that the <strong>fd:label</strong> tags can contain
mixed
--- content. On the one hand, this can be used to provide rich formatting in the
--- label. But it also enables you to put i18n-elements in there, to be
interpreted
--- by the I18nTransformer. This way, internationalisation is done using
standard
--- Cocoon techniques.</p>
+++ <p>A nice feature is that the <tt>fd:label</tt> tags can contain mixed
content.
+++ On the one hand, this can be used to provide rich formatting in the label.
But
+++ it also enables you to put i18n-elements in there, to be interpreted by the
+++ I18nTransformer. This way, internationalisation is done using standard
Cocoon
+++ techniques.</p>
--- <h1>Create a template file for the Forms Template Transformer</h1>
+++ <h1>Create a template file</h1>
--- <p>Here's the template for our registration form example:</p>
+++ <p>Here is the template for our registration form example,
+++ <tt>registration_template.xml</tt>:</p>
<pre><html xmlns:ft="http://apache.org/cocoon/forms/1.0#template";
--- xmlns:fi="http://apache.org/cocoon/forms/1.0#instance">
+++ xmlns:fi="http://apache.org/cocoon/forms/1.0#instance";
+++ xmlns:jx="http://apache.org/cocoon/templates/jx/1.0">
+++
+++ <jx:import
uri="resource://org/apache/cocoon/forms/generation/jx-macros.xml"/>
+++
<head>
<title>Registration form</title>
</head>
(31 equal lines skipped)
<p>The CForms-specific elements here are in the "Forms Template" namespace:
<strong>ft</strong>.</p>
--- <p>The <ft:widget-label> tag will cause the label of a widget to be
--- inserted at the location of the tag. The <ft:widget> tag will cause
the
--- XML representation of a widget to be inserted at the location of that tag.
The
--- inserted XML will be in the "Forms Instance" namespace:
<strong>fi</strong>.</p>
+++ <p>First, jx:import is used to import the CForms macros which execute the
+++ elements in the ft namespace.</p>
+++ <p>The <tt><ft:widget-label></tt> tag will cause the label of a
widget to
+++ be inserted at the location of the tag. The <tt><ft:widget></tt> tag
will
+++ cause the XML representation of a widget to be inserted at the location of
that
+++ tag. The inserted XML will be in the "Forms Instance" namespace:
+++ <strong>fi</strong>.</p>
+++
<p>The XML representation of the widget will then be translated to HTML by
an
XSLT stylesheet (forms-samples-styling.xsl in our case -- see sitemap
snippets
below). This XSLT only has to handle individual widgets, and not the page
as a
(23 equal lines skipped)
<pre>cocoon.load("resource://org/apache/cocoon/forms/flow/javascript/Form.js");
function registration() {
--- var form = new Form("forms/registration.xml");
+++ var form = new Form("registration_definition.xml");
form.showForm("registration-display-pipeline");
--- var model = form.getModel();
--- var bizdata = { "username" : model.name }
+++ var bizdata = { "username" : form.getChild("name").getValue() }
cocoon.sendPage("registration-success-pipeline", bizdata);
}</pre>
<p>The flowscript works as follows:</p>
--- <p>First we create a Form object, specifying the form definition file to be
--- used. The Form object is actually a javascript wrapper around the "real"
Java
--- form instance object.</p>
+++ <p>First we create a <tt>Form</tt> object, specifying the form definition
file
+++ to be used. The Form object is actually a javascript wrapper around the
"real"
+++ Java form instance object.</p>
--- <p>Then the showForm function is called on the form object. This will
+++ <p>Then the <tt>showForm</tt> function is called on the form object. This
will
(re)display the form to the user until validation of the form succeeded. As
parameter to the showForm function, we pass the sitemap pipeline to be used
to
display the form.</p>
(4 equal lines skipped)
<h1>Add some pipelines to the sitemap</h1>
--- <p>First of all, do not forget to register the <tt>registration.js</tt>
file in
--- the map:flow section of the sitemap, as follows:</p>
+++ <p>Here is the sitemap we need, <tt>sitemap.xmap</tt>:</p>
--- <pre><map:flow language="javascript">
--- <map:script src="flow/registration.js"/>
--- </map:flow></pre>
+++ <pre><?xml version="1.0"?>
+++ <map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">
--- <p>And here are the pipelines we need:</p>
+++ <map:components>
+++ <map:transformers default="xslt">
+++ <map:transformer name="i18n"
+++ src="org.apache.cocoon.transformation.I18nTransformer">
+++ <catalogues default="forms">
+++ <catalogue id="forms" name="messages"
+++ location="resource://org/apache/cocoon/forms/system/i18n"/>
+++ </catalogues>
+++ <cache-at-startup>true</cache-at-startup>
+++ </map:transformer>
+++ </map:transformers>
+++ </map:components>
--- <pre><map:match pattern="registration">
--- <map:call function="registration"/>
--- </map:match>
+++ <map:views>
+++ </map:views>
--- <map:match pattern="*.continue">
--- <map:call continuation="{1}"/>
--- </map:match>
+++ <map:resources>
+++ </map:resources>
--- <map:match pattern="registration-display-pipeline">
--- <map:generate src="forms/registration_template.xml"/>
--- <map:transform type="forms"/>
--- <map:transform type="i18n">
--- <map:parameter name="locale" value="en-US"/>
--- </map:transform>
--- <map:transform src="resources/forms-samples-styling.xsl"/>
--- <map:serialize/>
--- </map:match>
+++ <map:flow language="javascript">
+++ <map:script src="registration.js"/>
+++ </map:flow>
--- <map:match pattern="registration-success-pipeline">
--- <map:generate type="jx" src="forms/registration_success.jx"/>
--- <map:serialize/>
--- </map:match></pre>
+++ <map:pipelines>
--- <p>The first two are for managing the flowscript: when someone hits the
--- registration URL, we call the registration function in our flowscript.</p>
+++ <map:pipeline>
+++ <map:match pattern="registration">
+++ <map:call function="registration"/>
+++ </map:match>
--- <p>When a form is submitted, it will be matched by the second matcher,
--- *.continue, which will continue the execution of the flowscript.</p>
+++ <map:match pattern="*.continue">
+++ <map:call continuation="{1}"/>
+++ </map:match>
--- <p>The third matcher is for displaying the form, and uses the Forms Template
--- Transformer.</p>
+++ <map:match pattern="registration-display-pipeline">
+++ <map:generate type="jx" src="registration_template.xml"/>
+++ <map:transform type="i18n">
+++ <map:parameter name="locale" value="en-US"/>
+++ </map:transform>
+++ <map:transform src="forms-samples-styling.xsl"/>
+++ <map:serialize/>
+++ </map:match>
--- <p>The fourth pipeline is for showing the "success" page using the
JXTemplate
--- generator, here is the contents of the registration_succcess.jx page:</p>
+++ <map:match pattern="registration-success-pipeline">
+++ <map:generate type="jx" src="registration_success.jx"/>
+++ <map:serialize/>
+++ </map:match>
--- <pre><html>
+++ <map:match pattern="resources/**">
+++ <map:read src="resource://org/apache/cocoon/forms/{0}"/>
+++ </map:match>
+++
+++ </map:pipeline>
+++
+++ </map:pipelines>
+++
+++ </map:sitemap>
+++ </pre>
+++
+++ <p>Note the following things:</p>
+++
+++ <ul>
+++ <li>The i18n transformer is configured so it knows about the forms
messages. The
+++ forms catalogue does not have to be the default one, but here it is the
only one
+++ and thus the default.</li>
+++ <li>In the <tt>map:flow</tt> tag our flowscript file is declared.</li>
+++ <li>Then we have the pipelines:</li>
+++ <ul>
+++ <li>The first two are for managing the flowscript: when someone hits the
+++ registration URL, we call the registration function in our flowscript</li>
+++ <li>When a form is submitted, it will be matched by the second matcher,
+++ *.continue, which will continue the execution of the flowscript.</li>
+++ <li>The third matcher is for displaying the form. Note the JXTemplate
generator
+++ is used so that the form template tags get interpreted.</li>
+++ <li>The fourth pipeline is for showing the "success" page, again using the
+++ JXTemplate generator, the contents of the registration_succcess.jx file is
given
+++ below.</li>
+++ <li>The last one is for making default CForms resources available, such as
+++ javascript libraries, CSS files and images.</li>
+++ </ul>
+++
+++ </ul>
+++
+++ <p>As promised, here is the content of the <tt>registration_success.jx</tt>
+++ file:</p>
+++
+++ <pre><?xml version="1.0"?>
+++ <html>
<head>
<title>Registration successful</title>
</head>
<body>
Registration was successful for ${username}!
</body>
--- </html></pre>
+++ </html>
+++ </pre>
--- <h2>I18n Messages</h2>
+++ <p>One last thing you need to do is to copy the following file, which you
find
+++ in the Cocoon download, to your test directory:</p>
--- <p>Note that the above <tt>registration-display-pipeline</tt> pipeline uses
the
--- I18n transformer. This enables you to customise the messages generated by
the
--- form transformer. You will need to ensure that your I18n transformer is
--- correctly configured to find these messages. For example:</p>
+++ <pre>src/blocks/forms/samples/resources/forms-samples-styling.xsl</pre>
--- <pre><map:transformer name="i18n"
--- src="org.apache.cocoon.transformation.I18nTransformer">
--- <catalogues default="other">
--- <catalogue id="other" name="OtherMessages"
--- location="messages" />
--- <catalogue id="forms" name="FormsMessages"
--- location="messages" />
--- </catalogues>
--- <cache-at-startup>true</cache-at-startup>
--- </map:transformer></pre>
+++ <h1>Try it out</h1>
--- <p>You will also need to ensure that the indicated catalogues are available
--- within your webapp. You can find these catalogues in the
--- <a
href="http://svn.apache.org/viewcvs.cgi/cocoon/blocks/forms/trunk/samples/";>samples
--- directory Forms block</a>.</p>
+++ <p>If you have created all the files mentioned above, you can now try out
this
+++ sample by browsing to:</p>
+++ <pre>http://localhost:8888/myformtest/registration
+++ </pre>
+++
+++ <p>Try entering incorrect data and see what it does.</p>
+++
<h1>Next steps</h1>
--- <p>The example we've studied here is quite simple. To have a feel for the
power
--- of CForms, take a look at the examples included included in the Forms
block.</p>
+++ <p>The example we have studied here is quite simple. It might seem
elaborate for
+++ a simple form (though notice you didn't have to write any Java for all of
this,
+++ nor to restart Cocoon), but adding more complexity to the form is now
simply a
+++ matter of adding more widgets, custom validation logic, event handlers,
etc. To
+++ have a feel for the power of CForms, take a look at the examples included
+++ included in the Forms block.</p>
</body>
</html>
Fields
======
no changes
Links
=====
no changes
Custom Fields
=============
no changes
Collections
===========
no changes
