A Simple Example

A simple CForms example

In this example we will show how to create a simple registration form using CForms and flowscript. We will follow to following steps:

Create a form definition file
Create a template file
Write a bit of flowscript
Add some pipelines to the sitemap

You can try this sample out on a default Cocoon install. In the webapp directory (build/webapp), create a new subdirectory, for example called myformtest. In there, create the files as outlined in this sample.

Here is a screenshot of the form we're going to create:

Create a form definition file

Below the form definition file is displayed, registration_definition.xml. This lists all the widgets in the form, together with their configuration information.

<fd:form
  xmlns:fd="http://apache.org/cocoon/forms/1.0#definition">

  <fd:widgets>
    <fd:field id="name" required="true">
      <fd:label>Name:</fd:label>
      <fd:datatype base="string"/>
      <fd:validation>
        <fd:length min="2"/>
      </fd:validation>
    </fd:field>

    <fd:field id="email" required="true">
      <fd:label>Email address:</fd:label>
      <fd:datatype base="string"/>
      <fd:validation>
        <fd:email/>
      </fd:validation>
    </fd:field>

    <fd:field id="age">
      <fd:label>Your age:</fd:label>
      <fd:datatype base="long"/>
      <fd:validation>
        <fd:range min="0" max="150"/>
      </fd:validation>
    </fd:field>

    <fd:field id="password" required="true">
      <fd:label>Password:</fd:label>
      <fd:datatype base="string"/>
      <fd:validation>
        <fd:length min="5" max="20"/>
      </fd:validation>
    </fd:field>

    <fd:field id="confirmPassword" required="true">
      <fd:label>Re-enter password:</fd:label>
      <fd:datatype base="string"/>
      <fd:validation>
        <fd:assert test="password = confirmPassword">
          <fd:failmessage>The two passwords are not equal.</fd:failmessage>
        </fd:assert>
      </fd:validation>
    </fd:field>

    <fd:booleanfield id="spam">
      <fd:label>Send me spam</fd:label>
    </fd:booleanfield>
  </fd:widgets>

</fd:form>

All elements are in the Forms Definition namespace: fd.

Every definition file has a <fd:form> element as the root element.

The child widgets of the form are defined inside the <fd:widgets> 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.

A nice feature is that the fd:label 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.

Create a template file

Here is the template for our registration form example, registration_template.xml:

<html xmlns:ft="http://apache.org/cocoon/forms/1.0#template"
  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>
  <body>
    <h1>Registration</h1>
    <ft:form-template action="#{$continuation/id}.continue" method="POST">
      <ft:widget-label id="name"/>
      <ft:widget id="name"/>
      <br/>
      <ft:widget-label id="email"/>
      <ft:widget id="email"/>
      <br/>
      <ft:widget-label id="age"/>
      <ft:widget id="age"/>
      <br/>
      <ft:widget-label id="password"/>
      <ft:widget id="password">
        <fi:styling type="password"/>
      </ft:widget>
      <br/>
      <ft:widget-label id="confirmPassword"/>
      <ft:widget id="confirmPassword">
        <fi:styling type="password"/>
      </ft:widget>
      <br/>
      <ft:widget id="spam"/>
      <ft:widget-label id="spam"/>
      <br/>

      <input type="submit"/>
    </ft:form-template>
  </body>
</html>

The CForms-specific elements here are in the "Forms Template" namespace: ft.

First, jx:import is used to import the CForms macros which execute the elements in the ft namespace.

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: fi.

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 whole, and is thus not specific for one form but can be reused across forms.

For certain widgets it may be necessary to provide extra presentation hints, such as the width of a text box, the style of a selection list (drop down, radio buttons, ...) or class and style attribute values. This can be done by putting a fi:styling element inside the ft:widget element. This element is in the fi namespace because it will be copied literally. The attributes and/or content of the fi:styling element depend on what is supported by the particular stylesheet used.

As an alternative to the template approach, you could also use the FormsGenerator, which will generate an XML representation of the whole form, and style that with a custom-written XSLT. For most users we recommend the template approach though.

Write a bit of flowscript

Flowscript is Cocoon's solution to handling the flow of a web interaction. It is based on the concept of continuations. If you don't know yet about continuations and flowscript, learn about it here.

Here's the flowscript for our example, registration.js:

cocoon.load("resource://org/apache/cocoon/forms/flow/javascript/Form.js");

function registration() {
    var form = new Form("registration_definition.xml");

    form.showForm("registration-display-pipeline");

    var viewData = { "username" : form.getChild("name").getValue() }
    cocoon.sendPage("registration-success-pipeline", viewData);
}

The flowscript works as follows:

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.

Then the showForm 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.

Finally we get some data from the form (the entered name), and call a sitemap pipeline to display this data. This pipeline is based on the JXTemplate generator.

Add some pipelines to the sitemap

Here is the sitemap we need, sitemap.xmap:

<?xml version="1.0"?>
<map:sitemap xmlns:map="http://apache.org/cocoon/sitemap/1.0">

  <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>

  <map:views>
  </map:views>

  <map:resources>
  </map:resources>

  <map:flow language="javascript">
    <map:script src="registration.js"/>
  </map:flow>

  <map:pipelines>

   <map:pipeline>
     <map:match pattern="registration">
       <map:call function="registration"/>
     </map:match>

     <map:match pattern="*.continue">
       <map:call continuation="{1}"/>
     </map:match>

     <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>

     <map:match pattern="registration-success-pipeline">
       <map:generate type="jx" src="registration_success.jx"/>
       <map:serialize/>
     </map:match>

     <map:match pattern="resources/*/**">
       <map:read src="resource://org/apache/cocoon/{1}/resources/{2}"/>
     </map:match>

   </map:pipeline>

 </map:pipelines>

</map:sitemap>

Note the following things:

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.
In the map:flow tag our flowscript file is declared.
Then we have the pipelines:

The first two are for managing the flowscript: when someone hits the registration URL, we call the registration function in our flowscript
When a form is submitted, it will be matched by the second matcher, *.continue, which will continue the execution of the flowscript.
The third matcher is for displaying the form. Note the JXTemplate generator is used so that the form template tags get interpreted.
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.
The last one is for making default CForms resources available, such as javascript libraries, CSS files and images.

As promised, here is the content of the registration_success.jx file:

<?xml version="1.0"?>
<html>
  <head>
    <title>Registration successful</title>
  </head>
  <body>
    Registration was successful for ${username}!
  </body>
</html>

One last thing you need to do is to copy the following file, which you find in the Cocoon download, to your test directory:

src/blocks/forms/samples/resources/forms-samples-styling.xsl

Try it out

If you have created all the files mentioned above, you can now try out this sample by browsing to:

http://localhost:8888/myformtest/registration

Try entering incorrect data and see what it does.

Next steps

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.

Errors and Improvements? If you see any errors or potential improvements in this document please help us: View, Edit or comment on the latest development version (registration required).