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 trigger as seen in numerous examples in this book. The type of information that needs to be passed to a handler is different for each action based on the functionality it provides. The description that follows will focus on these differences; the eventing attributes common to all XForms actions will not be mentioned explicitly in the description for each action handler.
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 setfocus
Action setfocus is used to move focus to a specified XForms control. Element setfocus uses attribute control to identify the control that will receive focus. The value of this attribute is an idref of an XForms user interface control.
Action setfocus can be used to implement custom navigation within an online form. It can also be used to enable accessibility related functions such as quick navigation to a specified control.
7.2.2 Action setvalue
Action setvalue can be used to set a specific value in the instance . Attributes of element setvalue specify what value to set and where that value should be assigned. Thus, action setvalue can be thought of as an assignment statement, and its attributes can be classified as specifying the two sides of this assignment:
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:
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:
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 .
Required attribute level specifies the behavior to use when displaying the message. XForms specifies the following predefined values for attribute level :
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:
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:
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:
Table 7.1. Events and Corresponding Actions That Invoke XForms Processing
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 .
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.