Binding Framework

Likely you will want to use CForms to "edit stuff", such as the properties of a bean or data from an XML document (we'll simply use the term object to refer to either of these). This supposes that before you show the form, you copy the data from the object to the form, and after the form has been validated, you copy the data in the form back to the object. To avoid having to write actual code for this, a binding framework is available.

The same illustration as in the introduction, but now extended with the binding, can be viewed here.

The basic definition of a binding is as follows (if you don't know Java, just ignore this):

public interface Binding {
    public void loadFormFromModel(Widget frmModel, Object objModel);
    public void saveFormToModel(Widget frmModel, Object objModel);
}

A binding can work with any object and can perform the binding in any possible way. Currently one implementation is available, based on JXPath. JXPath allows to address data in both beans and XML documents using XPath expressions, so this binding implementation can be used both with beans and XML documents. The rest of this document will focus on this implementation.

The binding is configured using an XML file. This XML file contains elements in the fb namespace (Forms Binding):

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

To give you an idea of what a binding file looks like, below a very simple example is shown.

<fb:context xmlns:fb="http://apache.org/cocoon/forms/1.0#binding" path="/" >
    <fb:value id="firstname" path="firstName"/>
    <fb:value id="lastname" path="lastName"/>
    <fb:value id="email" path="email"/>
</fb:context>

The id attribute identifies the widget. The path attribute is the address of the items in the target object (a Javabean or an XML document). The paths can be arbitrary JXPath expressions.

[Convention] Let's call all elements in the fb namespace "binding elements". They all cause a binding-related action to be performed.

The fb:context element changes the JXPath context to the specified path. The path expressions on the binding elements occuring inside the context element will then be evaluated in this context, thus relative to the path specified on the fb:context element.

The fb:value element is used to bind the value of a widget.

The binding framework can do much more than what is shown in the simple example above, so read on for more meat.

Element	Description	Attributes	child elements
fb:*	common settings for all bindings	direction	not applicable, see specific elements
fb:context	changes the JXPath context	path	any
fb:value	binds the value of widgets	id, path	fb:on-update, fd:convertor
fb:aggregate	binds aggregatefield widgets	id, path	fb:value
fb:repeater	binds repeater widgets	id, parent-path, row-path	fb:identity, fb:on-bind, fb:on-delete-row, fb:on-insert-row
fb:identity	specifies unique fields for a repeater row	none	fb:unique-field
fb:set-attribute	sets an attribute to a fixed value	name, value	none
fb:delete-node	deletes the current context node	none	none
fb:insert-node	insert a node in an XML document	src, xpath	piece of XML that should be inserted
fb:insert-bean	inserts an object in a list-type bean property	addmethod, classname (optional)	none
fb:simple-repeater	binds repeater widgets	id, parent-path,row-path, clear-before-load, delete-parent-if-empty	any
fb:javascript	write binding logic in Javascript	id, path	fb:load-form, fb:save-form
fb:custom	write binding logic in Java	id, path, class, builderclass,factorymethod	fb:config

fb:*/@direction

All Bindings share the ability to have the two distinct actions they provide (i.e. load and save) been enabled or disabled by setting the attribute direction to one of the following values:

value	load active?	save active?
both(default)	yes	yes
load	yes	no
save	no	yes

The default value 'both' for this attribute makes its use optional.

NOTE: this setting replaces the @readonly attribute that was available only on selected bindings.

fb:context

Attributes:

• path
• direction (optional)

Child elements: any

The fb:context element changes the JXPath context to the specified path. The path expressions on the binding elements occuring inside the context element will then be evaluated in this context, thus relative to the path specified on the fb:context element.

The fb:context element is usually used in two occasions. First of all, it is used as the root element of the binding file; because an XML file must always have one root element, and you will usually want to perform more than one binding action.

Secondly, you use fb:context if you need to address multiple items having a common base path. On the one hand, this saves you on typing and helps readability, and on the other hand, this improves the performance of the binding. To illustrate this with an example, instead of doing this:

...
<fb:value id="firstname" path="info/person/firstName"/>
<fb:value id="lastname" path="info/person/lastName"/>
...

it is better to do this:

...
<fb:context path="info/person">
  <fb:value id="firstname" path="firstName"/>
  <fb:value id="lastname" path="lastName"/>
</fb:context>
...

fb:value

Attributes:

• id
• path
• direction (optional)

Child elements:

• fb:on-update (optional)
• fd:convertor (note the fd: namespace!) (optional)

This binding element is used to bind the value of a widget.

The fb:on-update element (which itself has no attributes), can contain one or more binding elements that will be executed if the value of the widget has changed, and thus if the object has been updated. For example, you could use the fb:set-attribute binding to set the value of an attribute changed to true.

The fd:convertor element has the same purpose as the fd:convertor element in the form definition: it converts between objects (numbers, dates) and strings. This is mostly used when binding to XML documents. Suppose you have defined a certain widget in a form definition to have a "date" datatype, and you want to bind to an XML document which contains the date in the XML Schema date representation, then you could define a convertor as follows:

<fb:value id="birthday" path="person/birthday">
  <fd:convertor datatype="date" type="formatting">
    <fd:patterns>
      <fd:pattern>yyyy-MM-dd</fd:pattern>
    </fd:patterns>
  </fd:convertor>
</fb:value>

The datatype attribute on the fd:convertor element, which you don't have to specify in the form definition, identifies the datatype to which the convertor belongs.

fb:aggregate

Attributes:

• id
• path
• direction

Child elements:

• fb:value elements

The fb:aggregate element is used to bind aggregatefields. Remember that aggregatefields are a special type of widget that groups multiple field widgets and lets the user edit their values in one textbox, splitting the values out to the different widgets on submit based on a regexp.

The fb:aggregate binding allows to bind the values of the individual field widgets out of which an aggregatefield widget consists. The bindings for these field widgets are specified by the fb:value child elements.

fb:repeater

Attributes:

• id
• parent-path
• row-path
• row-path-insert (optional)
• direction (optional)

Child elements:

• fb:identity
• fb:on-bind
• fb:on-delete-row
• fb:on-insert-row

The fb:repeater binding binds repeaters based on the concept that each row in the repeater is uniquely identified by the value(s) of one or more of its widgets. This unique identification is necessary to know which rows in the repeater correspond to which objects in the target collection, and is specified using a <fb:identity> child element.

The id attribute denotes the id of the repeater as specified in the form definition.

The parent-path and row-path attributes can best be understood when described differently for XML documents and Javabeans.

For XML documents: If you have an XML structure like this:

<things>
   <thing ... />
   <thing ... />
</things>

then the parent-path attribute contains the path to the containing element ("things") and the row-path attribute contains the path to the repeating element ("thing").

For beans: if your bean has a property "things" which is a Collection [or whathever JXPath supports as lists], then the parent-path should simply contain "." and the row-path "things".

For both beans and XML documents there is an optional attribute row-path-insert which functions just like the row-path but is used for the nested on-insert-row binding (see below). By default the row-path-insert just takes the value of the row-path. By explicitely setting them different one can exploit one of the following use cases:

• (1) use xpath-predicates in the row-path (note that you can not do that on the row-path-insert)
• (2) save the inserted rows in a different target-node of the backend model.

The three remaining child elements fb:on-bind, fb:on-delete-row, fb:on-insert-row should contain the binding elements that have to be executed in case of these three events.

The children of the fb:on-bind element are executed when an existing repeater row is updated, or after inserting a new row. The JXPath context is automatically changed to match the current row.

The children of the fb:on-delete-row element are executed when a repeater row has been deleted. If you want to delete the row, then put a <fb:delete-node/> in there. Alternatively, you could also use the fb:set-attribute binding to set e.g. an attribute status to deleted.

The children of the fb:on-insert-row are executed in case a new row has been added to the repeater. Typically this will contain a fb:insert-node or a fb:insert-bean binding (see the descriptions of these binding elements for more details).

fb:identity

Child elements:

• fb:value widget bindings constituting the repeater row identity

The <fb:identity> is just a container for the child elements specifying the bindings of the row identity widgets.

The nested elements just describe regular value bindings (these can declare their own convertors if needed). Newly added rows in the repeater can (but should not) have a null value for the identity widget(s). Identity widgets typically are uneditable and are specified as <fd:output> widgets. If you don't need the identity widget(s) at the client, you don't need to add them to the template at all! This prevents, e.g., database IDs from getting to the client.

NOTE: This 'identity' binding is only active in the 'load' operation, so specifying the direction="save" is meaningless.

fb:set-attribute

Attributes:

• name
• value
• direction (optional)

Child elements: none

Set the value of the attribute specified in the name attribute to the fixed string value specified in the value attribute.

NOTE: This binding is never active in the 'load' operation, so there is no need to specify the direction="save" to protect you model from being changed during load.

fb:delete-node

Attributes:

• direction (optional)

Child elements: none

Deletes the current context node.

NOTE: This binding is never active in the 'load' operation, so there is no need to specify the direction="save" to protect you model from being changed during load.

fb:insert-node

Attributes:

• src (optional)
• xpath (optional, only in combination with src)
• direction (optional)

Child elements: the piece of XML that should be inserted

This binding element can only be used when the target object is an XML document (DOM-tree).

It inserts the content of the fb:insert-node element as child of the current context element, or, if a src attribute is specified, retrieves the XML from the specified source and inserts that as child of the current context element. In this last case, you can also supply an xpath attribute to select a specific element from the retrieved source.

NOTE: This binding is never active in the 'load' operation, so there is no need to specify the direction="save" to protect you model from being changed during load.

fb:insert-bean

Attributes:

• addmethod
• classname (optional)
• direction (optional)

This binding element can only be used when the target object is a Javabean.

If classname is specified it instantiates a new object of the type specified in the classname attribute and calls the method specified in the addmethod attribute on the current context object with the newly instantiated object as argument. If classname is not specified it will just call the addmethod (e.g. if the addmethod creates the new instance itself).

NOTE: This binding is never active in the 'load' operation, so there is no need to specify the direction="save" to protect you model from being changed during load.

fb:simple-repeater

Attributes:

• id
• parent-path (same as in fb:repeater)
• row-path (same as in fb:repeater)
• clear-before-load (default true)
• delete-parent-if-empty (default false)
• direction (optional)

Child elements: any

A simple repeater binding that will replace (i.e. delete then re-add all) its content.

Works with XML or with JavaBeans if a JXPath factory is set on the binding context.

fb:javascript

Attributes:

• id
• path
• direction (optional)

Child elements:

• fb:load-form
• fb:save-form

Specifies the binding using two JavaScript snippets, respectively for loading and saving the form.

Example:

<fb:javascript id="foo" path="@foo">
  <fb:load-form>
    var appValue = jxpathPointer.getValue();
    var formValue = doLoadConversion(appValue);
    widget.setValue(formValue);
  </fb:load-form>
  <fb:save-form>
    var formValue = widget.getValue();
    var appValue = doSaveConversion(formValue);
    jxpathPointer.setValue(appValue);
  </fb:save-form>
</fb:javascript>

This example is rather trivial and could be replaced by a simple <fb:value>, but it shows the available variables in the script:

• widget: the widget identified by the id attribute,
• jxpathPointer: the JXPath pointer corresponding to the path attribute,
• jxpathContext (not shown): the JXPath context corresponding to the path attribute

It's much more interesting to fill a selection list via fb:javascript as there is no built-in element for it at the moment. Imagine your binding bean contains a collection field:

<fb:javascript id="selectionListWidget" path="objectCollection" direction="load">
  <fb:load-form>
    var collection = jxpathPointer.getNode();
    widget.setSelectionList(collection, "id", "name")
  </fb:load-form>
</fb:javascript>

NOTE:

• The <fb:save-form> snippet should be ommitted if the direction attribute is set to load.
• The <fb:load-form> snippet should be ommitted if the direction attribute is set to save.
• The @readonly attribute supported in early versions of this binding has been replaced by the @direction attribute as supported now on all binding elements.

fb:custom

Attributes:

• id (optional, if not provided the containing widget-context will be passed)
• path (optional, if not provided "." is assumed)
• direction (optional)
• class (optional, if not present @builderclass and @factorymethod should be)
• builderclass (optional)
• factorymethod (optional)

Child elements:

• fb:config

Allows to specify your own user-defined binding to be written in Java. There are two essential modes of operation reflected in two examples:

Example 1 - No configuration required:

<fb:custom id="custom" path="custom-value"
      class="org.apache.cocoon.forms.samples.bindings.CustomValueWrapBinding"/>

This describes the classname of your user defined binding class.

Above imposes the following requirements:

1. there is a class CustomValueWrapBinding available in the specified package
2. it has a default (i.e. no arguments) constructor
3. it is a subclass of org.apache.cocoon.forms.binding.AbstractCustomBinding

This last will impose the implementation of two methods:

• void doLoad(Widget widget, JXPathContext context) throws BindingException;
• void doSave(Widget widget, JXPathContext context) throws BindingException;

where the available arguments are

• widget: the widget identified by the id attribute,
• context: the JXPath context corresponding to the path attribute

Example 2 - with nested configuration:

  <fb:custom id="config" path="config-value"
      builderclass="org.apache.cocoon.forms.samples.bindings.CustomValueWrapBinding"
      factorymethod="createBinding" >
      <fb:config prefixchar="[" suffixchar="]" />
  </fb:custom>

The additional requirements to your user defined classes are now:

1. there is a builderclass CustomValueWrapBinding class having a static factorymethod
2. that can (optionally) take an org.w3c.dom.Element holding it's configuration
3. and return an instance of your own user-defined binding which must be a non abstract subclass of org.apache.cocoon.forms.binding.AbstractCustomBinding