Forms

At this point, our application allows us to navigate in our TaskBean objects, and we're ready to start editing them.

To take advantage of the Cocoon Forms editing features, we need the following:

• A pipeline to call the Flowscript handleForm() function (provided by the Cocoon Forms Flowscript library, Form.js) with the appropriate parameters.
• A Form Model file, to define the data model of our form.
• A Form Template file, to define the layout of our form while letting Cocoon Forms create the appropriate HTML elements to edit our form widgets.
• A Form Binding file, to define a mapping between the Form data model and our Java beans.

Note also that, while our example uses static XML files for these definitions, nothing prevents you from generating them dynamically using pipelines and the cocoon:/ protocol. If your application provides a central data dictionary, for example, it would be possible to generate at least simple versions of the required definition files automatically.

Sitemap

Let's look first at the pipeline definition for the edit/singleTask request:

What this does is to call the handleForm() function of the Form.js Flowscript library, telling it which of our own Flowscript function to call to edit the form, and indicating the locations of the Form Model (form-definition) and Form Binding documents.

Later, the Flowscript function shown below will call this pipeline:

Using the FormsTransformer to generate the appropriate HTML elements for our form's widgets.

Flowscript

Here's our Flowscript form editing function, called by the handleForm library function to edit our form:

0027 // Edit a single TaskBean object using Cocoon Forms
0028 function singleTaskEditor(form) {
0029    id = cocoon.request.getParameter("taskId");
0030    bean = db.getTaskBeanById(id);

0032    form.load(bean);
0033    form.showForm("internal/show-form/singleTask");
0034    form.save(bean);
0035    displayTaskBean(id,bean);
0036 }
            

Notice how simple and readable the code is - the magic happens behind the Cocoon Forms scenes, based on the Forms definitions shown below.

Form Model

Here's the definition of our Form Model.

As you can see, the Forms subsystem uses widgets with labels and datatypes to define a Model.

If you omit the repeater element above, this is a fairly simple data model which represents our form's data. The repeater is used to model the 1-N relationship between our TaskBean and TaskCommentBean objects.

Strongly typed fields are an important features of Cocoon Forms, and provide many standard validation features which make our life easier.

This model is independent from the way the form is going to look in HTML (or WML, or XUL, or whatever), and also independent of the internal structure of our Java beans.

Here we use constants for the widget labels (field names), but the i18n transformer could be added to our pipeline to easily generate views and forms in multiple languages.

Form Binding

Here's the binding definition, which allows the Forms subsystem to automatically move data from our Form's internal model to our Java beans.

This looks simple enough: for example, we tell the Forms subsystem that the form's taskId field is mapped in readonly mode to the bean's id field.

The data mapping is triggered by the Flowscript form.load and form.save calls shown above.

For the taskId form field, the readonly flag makes the binding unidirectional. The value of the form field will not be copied to the bean when form.save is called.

Form Template

Here's the template used by the FormsTransformer, which is activated by the above sitemap excerpt.

Based on the Form Model definition, The FormsTransformer replaces the <ft:widget> elements by the appropriate HTML input elements.

That's it!

Well, this time it certainly gets more complicated. But stand back and look at the code in the bean-editor/cocoon-app directory of this tour's files.

You will hopefully notice that we've written little "code", actually almost only definitions but very little actual code. Yet, the editing application is robust, easy to use, and very adaptable to different presentations or output devices.

Another important feature of the Cocoon Forms subsystem is its extensibility: a clean design makes it fairly easy to add custom Java classes for custom formatting, validation and bindings.