Templating

Introduction

CForms templates make it possible to define the layout for your form in a simple way. The basic principle is that you create a template file containing <ft:widget id="xyz"/> elements where you want to insert the widgets. After execution of the template, these will be replaced by the XML representation of the corresponding widgets. The ft:widget elements can thus be embedded in e.g. a HTML layout. After processing of the template tags you will end up with HTML with here and there a piece of XML describing a widget. This XML description contains all state information of the widget: its value, validation errors, selection-list data if any, and so on. These widget-XML-descriptions will then typically be translated to HTML by an XSLT. This XSLT is not specific to one form, as it simply needs to know how to translate individual widgets to HTML, and does not have to create the complete page layout. CForms contains just such an XSLT so you don't have to write it yourself (except if you need to do heavy customisation). The image below illustrates this process.

forms_template_transformer

Note: A completely different approach would be to do everything with XSLT, starting from the output of the FormsGenerator. In general we recommend to use the CForms templating approach though.

Available implementations

There are two different mechanisms available to process the form tags:

The JXTemplate-based approach is the newer one and is more powerful as you can make use of standard JX constructs in addition to the CForms template tags.

Locating the form instance object

In the most common case, the form object is passed by the flow controller to the pipeline in the view data under a key named "CocoonFormsInstance". There are alternative ways to locate the form, though these are dependent on the template implementation (JX or the transformer).

Forms transformer element reference

The elements to which the forms transformer reacts are all in the "ft" (Forms Template) namespace, which is identified by the following URI:

http://apache.org/cocoon/forms/1.0#template

These will generally be replaced by elements in the "fi" (Forms Instance) namespace, which is identified by the following URI:

http://apache.org/cocoon/forms/1.0#instance

A template should always consist of a ft:form-template tag which then contains the tags to insert the individual widgets. Widgets are most often inserted using the ft:widget tag, but some widgets might need specific tags. See the descriptions of the individual widgets for the appropriate template tags.

ft:widget

The ft:widget element is replaced by the forms transformer by the XML representation of a widget. Which widget is specified by the id attribute. The ft:widget element can contain a fi:styling element containing parameters to influence the styling process (the XSLT). The forms transformer will simply copy the fi:styling element over to its output.

For example:

<ft:widget id="pass">
  <fi:styling type="password"/>
<ft:widget/>

will be replaced by:

<fi:field id="pass">
  [... label, validation errors, ...]
  <fi:styling type="password"/>
</fi:field>

ft:widget-label

The ft:widget-label element will be replaced by the forms transformer with the label of a certain widget (specified by an id attribute). The label will not be wrapped in another element.

ft:continuation-id

The ft:continuation-id element will be replaced by the forms transformer by:

<fi:continuation-id>
  ID-of-the current-continuation
</fi:continuation-id>

This might be useful for embedding the continuation ID in a hidden form field, for example.

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

Cocoon Forms 1.0