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:


Event wiring using the facilities provided by XML Events described in Section 2.3.2


XForms binding expression that connects the handler to the underlying model where appropriate


Arguments that need to be passed to the handler

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:


The left side of the assignment is specified using XForms binding attributes. This is consistent with the mechanism used when binding controls to the instance ; in fact, the various user interface controls can be viewed as performing an implicit setvalue action when the user enters a value.


The value to assign can be specified in one of two ways:

  1. Specified via an XPath expression using attribute value . The expression will be evaluated, and the result becomes the right side of the assignment. Notice that using an XPath locator to address portions of the instance data can be used to advantage in copying values from one portion of the data model to another. Action setvalue assigns the string result of evaluating attribute value . Contrast this with element copy that can be used to copy entire subtrees.

  2. The right side of the assignment can be specified as text content of element setvalue .

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:


The URI to load can be located in the instance data by specifying an XForms binding expression.


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:

  1. User enters value for id .

  2. Completing the entry; for example, pressing enter raises event DOMActivate .

  3. The event is dispatched according to the rules defined by DOM2 Events and outlined in Figure 2.1.

  4. 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.

  5. The current instance is serialized and transmitted as specified by element submission .

  6. This performs a lookup, and the result is an XML instance that holds the user's current profile.

  7. 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.

  8. 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 .


The message can be provided inline as text content within body of element message .


The message can be placed in the instance data and addressed via an XForms binding expression.


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 :


The message is displayed for a short duration.


Explicit user action is needed to clear the message.


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:







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:


Names the event to dispatch


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 dependency relations among the nodes in the instance data.


Using the updated dependency relationships, recalculate the value of instance data nodes that need updating.


Ensure that the updated instance satisfies all static and dynamic validity constraints specified in the model.


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











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 repeat , for example, adding a new item to a shopping cart


Enables deletion of a node when using repeat , for example, removing an item from a shopping cart


Used to scroll through the underlying nodes when using repeat

XForms. XML Powered Web Forms with CD
XForms. XML Powered Web Forms with CD
Year: 2003
Pages: 94

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net