7.2 Declarative Event Handlers
| Declarative action handlers capture the high-level meaning of the action to perform. The details of how the action is implemented in a given client or device is left to the underlying implementation. This allows XForms authors to focus on the higher-level aspects of the interaction they create; it also ensures that such interaction is easily deployed to a variety of devices and environments. XForms action handlers encode the following pieces of information:
XForms action handlers are used within control The mechanism provided by XML Events is used to connect events to the handlers they invoke. The actions performed by these declarative handlers can in turn be described in terms of the events they dispatch. The description of the actions in this chapter will mention this correspondence between actions and the events they dispatch where appropriate. The complete mapping between XForms actions and XForms events will be presented in Chapter 8 after we have covered the events defined in XForms 1.0. 7.2.1 Action |
| LHS | The left side of the assignment is specified using XForms binding attributes. This is consistent with the mechanism used when binding controls to the |
| RHS | The value to assign can be specified in one of two ways:
|
| If neither attribute value nor text content is present, the effect is to set the value of the selected node to the empty string. If both are present, attribute value is used. |
7.2.3 Action 
load 
Action load is used to load a specified resource, for example, an external document specified by its URL. The resource to load is specified in one of two mutually exclusive ways:
| Instance | The URI to load can be located in the instance data by specifying an XForms binding expression. |
| XLink | XLink [1] is a W3C Recommendation for specifying extensible linking behavior. This mechanism can be used to specify the resource to load and the behavior that is exhibited in loading that resource via attributes resource and show . |
[1] http://www.w3.org/tr/xlink
7.2.4 Action send
We described user interface control submit and the associated submit processing in Section 3.8. Control submit achieves the functionality described by implicitly invoking action send . The submission to invoke is specified via attribute submission of action send , and its meaning is the same as the attribute of the same name on control submit .
Having access to submit processing via an explicit action handler has a number of advantages when creating rich user experiences. As an example, XForms authors can create an implicit submit control by invoking action send when the user finishes interacting with a given control.
We illustrate such implicit submission in Figure 7.1 where we attach action send to control input used to collect the user's id . When the user completes this field, the resulting DOMActivate event invokes the attached send action. The submission performs a lookup of the user's subscription information, and the results are reflected in the user interface. This is achieved by specifying a value of instance for attribute replace in element submission .
Figure 7.1 Reflecting the result of an automatic lookup.
< html xmlns ="http://www.w3.org/1999/xhtml" xmlns:ev ="http://www.w3.org/2001/xml-events" xmlns:xf ="http://www.w3.org/2002/xforms"> < head > < xf:model id ="profile" schema ="person.xsd"> < xf:instance xmlns ="" id ="p1"> < person >< id />...</ person ></ xf:instance > < submission id ="lookup" replace ="instance" action ="http://examples.com/person/lookup"/> </ xf:model ></ head > < body > < group xmlns ="http://www.w3.org/2002/xforms"> < input ref ="/person/id">< label >User ID</ label > < help >...</ help > < hint >If subscribed, providing your ID will display your current profile.</ hint > < send ev:event ="DOMActivate" submission ="lookup"/></ input > <!-- UI bound to < person >...</ person >--> </ group > </ body ></ html >
Following we enumerate the sequence of events and actions for the example shown in Figure 7.1:
-
User enters value for
id . -
Completing the entry; for example, pressing enter raises event DOMActivate .
-
The event is dispatched according to the rules defined by DOM2 Events and outlined in Figure 2.1.
-
The event is handled by action
send . Action send causes submit processing as declared in element submission . This is initiated by dispatching event xforms-submit to the specified submission element. -
The current
instance is serialized and transmitted as specified by element submission . -
This performs a lookup, and the result is an XML instance that holds the user's current profile.
-
This XML instance is returned as the server response. The value of attribute replace is instance ; consequently, the server response is interpreted as an update to the instance data.
-
The updated instance is loaded into the form; as a result, user interface controls bound to the instance data are updated to display the newly received values.
Notice that action send performs its action by dispatching event xforms-submit to the desired submission element. An immediate consequence of this design is that the XForms author can hook custom behavior that is invoked before the submission takes place. We saw an example of this in Figure 6.5 where we attached action message to element submission .
7.2.5 Action reset
Action reset can be used to clear all values entered by the user and to restore the instance data to its initial state. This action affects only the specified model and can therefore be used in an XForms application with multiple models. The id of the model to reset is specified via attribute model . Action reset dispatches an xforms-reset event to the specified model. Thus, like the rest of the XForms processing model, authors can hook custom behavior to reset processing by attaching an event listener that responds to event xforms-reset . An accessibility application might use this feature to advantage in alerting the user that the form is about to be cleared.
7.2.6 Action message
Action message displays (or otherwise conveys) the specified message to the user. The message to convey can be specified in multiple ways as with action setvalue .
| Inline | The message can be provided inline as text content within body of element |
| Instance | The message can be placed in the instance data and addressed via an XForms binding expression. |
| External | The message can be located in an external resource that is specified via XLink. |
Required attribute level specifies the behavior to use when displaying the message. XForms specifies the following predefined values for attribute level :
| ephemeral | The message is displayed for a short duration. |
| modal | Explicit user action is needed to clear the message. |
| modeless | This is used in visual environments for displaying pop-up help. |
As with attributes like appearance , implementors can experiment with other values for attribute level as long as these values are in a specific namespace.
Notice that the help and hint facilities provided by all XForms user interface controls is syntactic sugar for attaching action message to the corresponding events as follows:
| Element | Event |
|---|---|
| | xforms-help |
| | xforms-hint |
We demonstrate this equivalence in Figure 7.2 by creating two instances of the same input control. The first uses elements help and hint ; the second encodes the same information via action message .
Figure 7.2 Action message used to implement help and hint .
< group xmlns ="http://www.w3.org/2002/xforms" xmlns:ev ="http://www.w3.org/2001/xml-events"> <!--Using elements help and hint --> < input ref ="age">< label >Age</ label > < help >Specify your age as a number.</ help > < hint >How old are you?</ hint ></ input > <!-- Using action message --> < input ref ="age">< label >Age</ label > < message ev:event ="xforms-help" level ="modal"> Specify your age as a number.</ message > < message ev:event ="xforms-hint" level ="modeless"> How old are you? </ message > </ input ></ group >
7.2.7 Action action
Action action can be used to group handlers when more than one action is to be attached for a specified event. Thus, its role is similar to that played by braces in languages like C and Java when creating compound statements. Actions enclosed in action have one additional special behavior: Steps performed by the XForms processing model such as rebuilding dependency relations is deferred while the actions inside an action grouping are invoked. See Section 7.2.9 for a list of such actions. This deferred processing is relevant in advanced applications where it can be advantageous to recompute interdependencies after a group of changes has been propagated to the model.
The role of action action is to attach a group of handlers to a single event. The event to listen for must be specified on element action , not via event attributes on any of the contained actions. The reason for this is the default rules used by module XML Events in determining the observer (see Section 2.3). We illustrate this with an example in Figure 7.3.
Figure 7.3 Insert control that sets the value of the inserted node.
< group xmlns ="http://www.w3.org/2002/xforms" xmlns:ev ="http://www.w3.org/2001/xml-events"> < trigger > < label >Add Special Item</ label > < action ev:event ="DOMActivate"> < insert nodeset ="cart" at ="index('cart')" position ="after"/> < setvalue ref ="cart[index('cart')]" value ="9"/> </ action ></ trigger > </ group >
The example contains a trigger control that implements a specialized insert control. A new node is inserted into a repeat collection, and the value of the newly inserted node is set to 9. Notice that, in this example, XML Events attribute ev:event must be placed on element action . Placing this attribute on either of the contained actions would have no effect. This is because the example relies on the defaulting of XML Events attributes observer and handler . As defined in the XML Events specification, if both observer and handler are omitted, then the parent is the observer. Thus, placing attribute ev:event on the children of element action would cause element action to become the observer for the individual events.
Consequently, these actions will never be triggered, since events arrive at element trigger , not at element action .
7.2.8 Action dispatch
Action dispatch enables the XForms author to dispatch explicit events during the course of user interaction. As mentioned earlier, the operation of the various declarative actions can be described in terms of the events they dispatch; in fact, many of these actions can be thought of as syntactic sugar for action dispatch with the appropriate arguments. Action dispatch takes the following items of information:
| name | Names the event to dispatch |
| target | Identifies the target node to which the event should be dispatched |
Events that are defined as part of the XForms processing model ”see Chapter 8 ”start with the prefix xforms- . These events have special bubble and cancel semantics as defined in the XForms 1.0 specification. For all other event types, the XForms author can specify bubble and cancel behavior via the XML Events attributes of the same name.
7.2.9 Invoking XForms Processing
The XForms processing model is responsible for keeping the rendered user interface in sync with the underlying data model. As the user interacts with the XForms application, values in the instance get updated, and this triggers default XForms processing which involves the following steps:
| Rebuild | Rebuild dependency relations among the nodes in the instance data. |
| Recalculate | Using the updated dependency relationships, recalculate the value of instance data nodes that need updating. |
| Revalidate | Ensure that the updated instance satisfies all static and dynamic validity constraints specified in the model. |
| Refresh | Refresh the user interface by reflecting all updates to the instance data in the presentation layer. This includes refreshing all controls whose underlying data has changed, as well as displaying the necessary alert messages for invalid instance data. |
Table 7.1. Events and Corresponding Actions That Invoke XForms Processing
| Action | Event |
|---|---|
| | xforms-rebuild |
| | xforms-recalculate |
| | xforms-revalidate |
| | xforms-refresh |
By default, the XForms processor invokes the above steps as the user interacts with the various user interface controls. However, authors can explicitly invoke these steps via declarative action handlers. These actions, enumerated as follows, have the same names as the processing step they invoke. In addition to the standard eventing attributes, each of these actions takes the id of the model to process via attribute model . When these actions are enclosed within action action , their processing is deferred .
| | Rebuilds the dependency relations for the specified model |
| | Recalculates all instance nodes having property calculate in the specified model |
| | Revalidates instance data in the specified model |
| | Redisplays all user interface controls that bind to updated instance data in the specified model |
Each of these actions invokes the specified processing step by dispatching the appropriate event to the specified model; the correspondence between these declarative actions and events is shown in Table 7.1.
7.2.10 Actions insert , delete , and setindex
XForms defines three special declarative handlers for use with repeat . These action handlers are described in Section 4.3.4 and are summarized following for completeness.
| | Enables insertion of a node when using |
| | Enables deletion of a node when using |
| | Used to scroll through the underlying nodes when using |
