Template Transformer

Introduction

The Forms Template Transformer can execute the CForms template tags.

Usage

For how to declare this transformer and how to embed it in a pipeline, see the Cocoon samples (the lazy doc writer approach).

Special features of the forms transformer

Where the forms transformer looks for the form instance object

Each time the forms transformer encounters a ft:form-template element, it will try to retrieve a CForms form instance object. It looks for it in the following locations:

if the ft: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.
if a parameter called "attribute-name" was supplied to the forms transformer in the sitemap, then the forms 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)
finally, the forms transformer will look if a CForms form was supplied from a flowscript using the key "CocoonFormsInstance".

If the form is not found at any of these locations, an exception is thrown. 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:

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

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

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

Action attribute on ft:form-template

The forms transformer supports the execution of JXPath expressions that occur in the action attribute of the ft:form-template element. This makes it possible to embed the continuation ID in that attribute.

For example:

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

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

Note that the JXTemplate-based form-template-tag-implementation of course also supports this, as this is a native feature of JXTemplate.