cocoon-docs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From da...@cocoon.zones.apache.org
Subject [DAISY] Updated: Cocoon Forms: A Simple Example
Date Wed, 19 Oct 2005 18:50:30 GMT
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>&lt;fd:form
      xmlns:fd="http://apache.org/cocoon/forms/1.0#definition"&gt;
(51 equal lines skipped)
    
    <p>All elements are in the Forms Definition namespace: <strong>fd</strong>.</p>
    
--- <p>Every definition file has a <strong>&lt;fd:form&gt;</strong>
element as the
--- root element.</p>
+++ <p>Every definition file has a <tt>&lt;fd:form&gt;</tt> element
as the root
+++ element.</p>
    
    <p>The child widgets of the form are defined inside the
--- <strong>&lt;fd:widgets&gt;</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>&lt;fd:widgets&gt;</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>&lt;html xmlns:ft="http://apache.org/cocoon/forms/1.0#template"
---   xmlns:fi="http://apache.org/cocoon/forms/1.0#instance"&gt;
+++   xmlns:fi="http://apache.org/cocoon/forms/1.0#instance"
+++   xmlns:jx="http://apache.org/cocoon/templates/jx/1.0"&gt;
+++ 
+++   &lt;jx:import uri="resource://org/apache/cocoon/forms/generation/jx-macros.xml"/&gt;
+++ 
      &lt;head&gt;
        &lt;title&gt;Registration form&lt;/title&gt;
      &lt;/head&gt;
(31 equal lines skipped)
    <p>The CForms-specific elements here are in the "Forms Template" namespace:
    <strong>ft</strong>.</p>
    
--- <p>The &lt;ft:widget-label&gt; tag will cause the label of a widget to be
--- inserted at the location of the tag. The &lt;ft:widget&gt; 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>&lt;ft:widget-label&gt;</tt> tag will cause the label
of a widget to
+++ be inserted at the location of the tag. The <tt>&lt;ft:widget&gt;</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>&lt;map:flow language="javascript"&gt;
---   &lt;map:script src="flow/registration.js"/&gt;
--- &lt;/map:flow&gt;</pre>
+++ <pre>&lt;?xml version="1.0"?&gt;
+++ &lt;map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0"&gt;
    
--- <p>And here are the pipelines we need:</p>
+++   &lt;map:components&gt;
+++     &lt;map:transformers default="xslt"&gt;
+++       &lt;map:transformer name="i18n"
+++         src="org.apache.cocoon.transformation.I18nTransformer"&gt;
+++         &lt;catalogues default="forms"&gt;
+++           &lt;catalogue id="forms" name="messages"
+++             location="resource://org/apache/cocoon/forms/system/i18n"/&gt;
+++         &lt;/catalogues&gt;
+++         &lt;cache-at-startup&gt;true&lt;/cache-at-startup&gt;
+++       &lt;/map:transformer&gt;
+++     &lt;/map:transformers&gt;
+++   &lt;/map:components&gt;
    
--- <pre>&lt;map:match pattern="registration"&gt;
---   &lt;map:call function="registration"/&gt;
--- &lt;/map:match&gt;
+++   &lt;map:views&gt;
+++   &lt;/map:views&gt;
    
--- &lt;map:match pattern="*.continue"&gt;
---   &lt;map:call continuation="{1}"/&gt;
--- &lt;/map:match&gt;
+++   &lt;map:resources&gt;
+++   &lt;/map:resources&gt;
    
--- &lt;map:match pattern="registration-display-pipeline"&gt;
---   &lt;map:generate src="forms/registration_template.xml"/&gt;
---   &lt;map:transform type="forms"/&gt;
---   &lt;map:transform type="i18n"&gt;
---     &lt;map:parameter name="locale" value="en-US"/&gt;
---   &lt;/map:transform&gt;
---   &lt;map:transform src="resources/forms-samples-styling.xsl"/&gt;
---   &lt;map:serialize/&gt;
--- &lt;/map:match&gt;
+++   &lt;map:flow language="javascript"&gt;
+++     &lt;map:script src="registration.js"/&gt;
+++   &lt;/map:flow&gt;
    
--- &lt;map:match pattern="registration-success-pipeline"&gt;
---   &lt;map:generate type="jx" src="forms/registration_success.jx"/&gt;
---   &lt;map:serialize/&gt;
--- &lt;/map:match&gt;</pre>
+++   &lt;map:pipelines&gt;
    
--- <p>The first two are for managing the flowscript: when someone hits the
--- registration URL, we call the registration function in our flowscript.</p>
+++    &lt;map:pipeline&gt;
+++      &lt;map:match pattern="registration"&gt;
+++        &lt;map:call function="registration"/&gt;
+++      &lt;/map:match&gt;
    
--- <p>When a form is submitted, it will be matched by the second matcher,
--- *.continue, which will continue the execution of the flowscript.</p>
+++      &lt;map:match pattern="*.continue"&gt;
+++        &lt;map:call continuation="{1}"/&gt;
+++      &lt;/map:match&gt;
    
--- <p>The third matcher is for displaying the form, and uses the Forms Template
--- Transformer.</p>
+++      &lt;map:match pattern="registration-display-pipeline"&gt;
+++        &lt;map:generate type="jx" src="registration_template.xml"/&gt;
+++        &lt;map:transform type="i18n"&gt;
+++          &lt;map:parameter name="locale" value="en-US"/&gt;
+++        &lt;/map:transform&gt;
+++        &lt;map:transform src="forms-samples-styling.xsl"/&gt;
+++        &lt;map:serialize/&gt;
+++      &lt;/map:match&gt;
    
--- <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>
+++      &lt;map:match pattern="registration-success-pipeline"&gt;
+++        &lt;map:generate type="jx" src="registration_success.jx"/&gt;
+++        &lt;map:serialize/&gt;
+++      &lt;/map:match&gt;
    
--- <pre>&lt;html&gt;
+++      &lt;map:match pattern="resources/**"&gt;
+++        &lt;map:read src="resource://org/apache/cocoon/forms/{0}"/&gt;
+++      &lt;/map:match&gt;
+++ 
+++    &lt;/map:pipeline&gt;
+++ 
+++  &lt;/map:pipelines&gt;
+++ 
+++ &lt;/map:sitemap&gt;
+++ </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>&lt;?xml version="1.0"?&gt;
+++ &lt;html&gt;
      &lt;head&gt;
        &lt;title&gt;Registration successful&lt;/title&gt;
      &lt;/head&gt;
      &lt;body&gt;
        Registration was successful for ${username}!
      &lt;/body&gt;
--- &lt;/html&gt;</pre>
+++ &lt;/html&gt;
+++ </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>&lt;map:transformer name="i18n"
---   src="org.apache.cocoon.transformation.I18nTransformer"&gt;
---   &lt;catalogues default="other"&gt;
---     &lt;catalogue id="other" name="OtherMessages"
---       location="messages" /&gt;
---     &lt;catalogue id="forms" name="FormsMessages"
---       location="messages" /&gt;
---     &lt;/catalogues&gt;
---   &lt;cache-at-startup&gt;true&lt;/cache-at-startup&gt;
--- &lt;/map:transformer&gt;</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

Mime
View raw message