Binding

9.1 Introduction

Binding is the glue that connects the separate pieces of XForms--the XForms Model, instance data, and form controls. The binding is independent of the user interface language used.

Binding is specified through the use of binding expressions. The syntax and details of binding expressions are defined in the chapter 6 XPath Expressions in XForms. This chapter describes the wider topic of how binding expressions are used within XForms.

A future revision of this chapter will address binding across XForms Models, for instance declaring an "address" in one XForms Model and referencing it from another.

9.2 Binding Attributes

XForms defines an attribute ref that can be placed on any form control. Note that when placed on form controls outside of XForms, it must be appropriately namespace-qualified. The value of the attribute is a binding expression, based on 6 XPath Expressions in XForms, that links the form control to a particular location in the instance data (and therefore a particular model item). For example:

Example: XForms User Interface Markup with Binding Attributes

<xform:textbox ref="binding-expression">
   <xform:caption>Your first name</xform:caption>
</xform:textbox>

The ref attribute links the form control to the instance data and XForms Model declared elsewhere in the containing document.

This can also be used on non-XForms form controls, for instance XHTML:

Example: XHTML with Binding Attributes

<html:input type="text" name="..." xform:ref="binding-expression"/>

Here the ref attribute links an XHTML form control to the instance data and XForms Model contained elsewhere in the containing document. Note that the html: prefix is used here to represent the XHTML namespace.

Details on the operation of binding expressions are given throughout the rest of this chapter.

9.3 Direct Binding

When a containing document has only a single XForms Model and only a single set of instance data, binding is simpler because there is no possibility of ambiguity as to which XForms Model and instance data will participate. The following syntax can be used for the binding expression:

A binding expression that evaluates to a node-set in the instance data. If the node-set contains more than one node, only the first node is used. If the node-set contains zero nodes, the binding expression is invalid.

For example:

Example: Binding Expression

<xform:textbox ref="orderForm/shipTo/firstName">
...

Here the ref attribute specifies a path through the instance data to the desired location.

<orderForm>
  <shipTo>
    <firstName>value</firstName>
  </shipTo>
</orderForm>

Here is the matching instance data for the above example.

A special case applies when binding to an element in the instance data that contains an attribute of type xsd:ID. In this case, an XPath function id(), can be used:

Example: Binding Expression with XPath id() Syntax

<xform:textbox ref="id('myfirstname')">
...

Here the ref attribute specifies a link to an instance data element with an id of myfirstname.

<a>
  <b id="myfirstname">value</b>
</a>

Here is the instance data for the above example.

For this syntax to be valid, the following conditions must be true:

The instance data must be included in the same document as the XForms User Interface
Every referenced element in the instance data must be marked with a valid ID (i.e. the ID is unique throughout the whole document)

Note also that:

this method is limited, because it requires exactly one instance, decorated with ID attributes.
It is still legal to have elements without ID attributes in the instance data.
Only elements can be addressed

9.4 Indirect Binding

In situations where a form is designed by collaboration (such as between a graphic designer and a database/XML specialist) it is desirable to locate all binding expressions in a single area in the containing document. XForms allows the binding expression to appear in a separate element bind, a child of the xform element.

The attributes of bind are id of type xsd:ID and ref which takes a binding expression. When a binding expression is defined this way, the form control can reference the id of the bind element, as seen here:

Example: Binding Expression Using Indirection

<xform:textbox ref="id('myfirstname')">
...

Here the ref attribute specifies a link to a binding expression defined elsewhere.

<xform:bind id="myfirstname" ref="orderForm/shipTo/firstName"/>
<xform:instance>
  <orderForm>
    <shipTo>
      <firstName>value</firstName>
    </shipTo>
  </orderForm>
</xform:instance>

Here is the instance data for the above example.

This accomplishes the following:

It is no longer necessary to add IDs to the instance.
The binding mechanism is independent of the schema and user interface mechanisms.

9.5 Multiple Forms per Page

One design goal of XForms is to support multiple forms per page. This is accomplished by having multiple xform elements within a containing document. Each xform element might have a separate XForms Model or instance data defined. This makes binding slightly more complex, because the correct xform element needs to be referenced.

By default, binding expressions are based on the instance data associated with the first xform element in document order. To refer to the contents of subsequent xform elements, these must be decorated with id attributes of type xsd:ID. Attached to the form control element, an additional attribute xform serves to set the context node for the attached binding expression to the instance data or XForms Model associated with the xform element with the matching id.