!WoodyTemplateTransformer

The WoodyTemplateTransformer (simply "woody transformer" from now on) makes it possible to define the layout for your form without having to write a separate XSLT for each form. If you prefer to do everything with XSLT, you have also the option of using the WoodyGenerator. In general we recommend to use the woody transformer though.

The basic principle is that the woody transformer will replace any <wt:widget id="xyz"/> elements it encounters by the XML representation of the corresponding widgets. These wt:widget elements can be embedded in e.g. a HTML layout. So after passing this template through the woody transformer you'll 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 then however not form-specific, as it simply needs to know how to translate individual widgets to HTML, and does not have to create the complete page layout. Woody 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.

http://outerthought.net/~bruno/images/woody_template_transformer.png

Where the woody transformer looks for the Woody form object

Each time the woody transformer encounters a wt:form-template element (see further on), it will try to retrieve a woody form instance object. It looks for it in the following locations:

  1. if the wt:form-template element has a location attribute, then the value of that attribute will be evaluated as a JXPath expression. The result of this expression should be the form object.
  2. if a parameter called "attribute-name" was supplied to the woody transformer in the sitemap, then the woody transformer will try to find the form in the request attribute with that name. (request attributes are a temporary storage area that exists for the duration of one request and is often used to communicate objects between different sitemap components such as actions and transformers)
  3. finally, the woody transformer will look if a woody form was supplied from a flowscript using the key "woody-form".

If the form is not found at any of these locations, an exception is thrown.

Woody transformer element reference

The elements to which the woody transformer reacts are all in the "wt" (Woody Template) namespace, which is identified by the following URI:

http://apache.org/cocoon/woody/template/1.0

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

http://apache.org/cocoon/woody/instance/1.0

wt:form-template

The wt:form-template element is always required; all other wt:* elements should occur inside a wt:form-template element. As described earlier, when the woody transformer encounters the wt:form-template element it will try to look up the woody form instance object.

wt:form-template elements may not be nested.

The wt:form-template will by default copy over all attributes appearing on it, except for one attribute called "location", and it will also take special care of the action attribute.

The action attribute can contain JXPath expressions. As with the JX!TemplateGenerator, these JXPath expressions must be embedded inside #{ and }. By allowing the use of JXPath expressions, you can embed dynamic data in the action attribute. One of the most common uses is to embed the continuation id (if you're using flowscript), for example:

<wt:form-template action="#{$continuation/id}.continue" ...

The following objects are available in the JXPath context: continuation, requests, session and parameters. The context of the JXPath expression is the map passed on from the flowscript (if any).

The location attribute, if present, is used to retrieve the form instance object. The value of the location attribute should be a JXPath expression, and is executed in the same context as the JXPath expressions embedded in the action attribute.

For example, if your form object is stored in the session using the key "myform", then following expression in the location attribute can be used to retrieve it:

<wt:form-template location="getAttribute($session, 'myform')" ...

If you'd like to retrieve the key "myform" from a parameters specified in the sitemap, say one called "sessionattr", then the following can be used:

<wt:form-template location="getAttribute($session, getParameter($parameters, 'sessionattr'))" ...

As mentioned before, wt:form-template elements cannot be nested, but you can have multiple wt:form-template elements on one page. Together with the location attribute, this can be used to handle multiple forms occuring on one template.

wt:widget

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

For example:

<wt:widget id="pass">
  <wi:styling type="password"/>
<wt:widget/>

will be replaced by:

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

Note: it is not recommended to use the older approach, i.e. without the wi:styling element, anymore, since support for it will be dropped at some point in the future.

wt:widget-label

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

wt:continuation-id

The wt:continuation-id element will be replaced by the woody transformer by:

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

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

Working with repeaters: wt:repeater-widget, wt:repeater-widget-label, wt:repeater-size

The wt:repeater-widget element is similar to the wt:widget element but provides special treatment for repeaters. The content of the wt:repeater-widget element will be used as a template to generate each of the rows of the repeater.

The wt:repeater-widget-label element is used to retrieve the label of a widget contained by a repeater. It requires two attributes: id (identifying the repeater) and widget-id (identifying the widget in the repeater).

The wt:repeater-size element inserts an element <wi:repeater-size id="..." size="..."/> containing the size (number of rows) of the repeater.

For an example of how this all fits together, take a look at the samples included in the woody block.

WoodyTemplateTransformer (last edited 2009-09-20 23:40:59 by localhost)