8.4 Notification Events

Interaction events are raised as a result of explicit user action, for example, changing a value or navigating to a user interface control. In contrast, notification events are raised by the XForms processor to signal changes of state that require other processing steps to be initiated. Notification events provide a useful hook for XForms authors to attach custom behaviors. Below, we group these various notification events based on their function.

8.4.1 Setting Values

User input provided via XForms controls is finalized , that is, propagated to the bound instance when the user activates the control. The specific user action that activates a control varies, based on the user interface control as well as on the device in use. As an example, a desktop browser might use the pressing of the enter key to activate an input control. All such activation raises event DOMActivate , and this event provides a platform-neutral means for attaching custom behavior to be triggered when a control is activated. We used this event in attaching action send in Figure 7.1 to trigger an automatic lookup. This event is targeted at the user interface control to activate; the event can be canceled or allowed to bubble .

Event xforms-value-changed is raised when the value is finalized and can be used to create custom controls that alert the user to such state changes, for example, by triggering an action that speaks a confirmatory message.

8.4.2 Select and Deselect Notifications

XForms defines events xforms-select and xforms-deselect that are raised in response to user actions that result in selection and deselection. XForms selection controls select1 and select allow the user to select from a set of values (see Section 3.4). Both of these controls use common element item to specify the alternatives in the case of static selections and element itemset when creating dynamic selections. User interaction with static and dynamic selections raises events xforms-select and xforms-deselect . The events are targeted at the item that is being selected or deselected.

Advanced XForms applications can attach actions to these events to update other portions of the interface automatically as the user changes the state of controls select or select1 . As an example, consider an online bookstore that displays a list of authors and the list of books by a selected author. The XForms author can create a dynamic end-user experience by attaching an implicit send action to event xforms-select for the author list control. This results in the displayed list of books being automatically updated whenever the user selects a different author (see Figure 8.1).

Figure 8.1 Dynamically updating a book list as authors are selected.

 <  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  ><  title  >Book Catalog</  title  >     <  model   id  ="books"  schema  ="bookstore.xsd">       <  instance   id  ="authors"  src  ="authors.xml"/>       <  instance   id  ="s"  xmlns  ="">         <  shelf  >           <  author  />           <  books  ><  book  >...</  book  ></  books  >       </  shelf  ></  instance  >       <  submission   id  ="update"  replace  ="instance"  ref  ="instance('s')"  action  ="http://example.com/bookstore/lookup"/>   </  model  ></  head  >   <  body   xmlns  ="http://www.w3.org/2002/xforms">     <  select1   ref  ="instance('s')/author">       <  label  >Select Author</  label  >       <  itemset   ref  ="instance('authors')/author">         <  label   ref  ="."/><  value   ref  ="@author-id"/>         <  send   ev:event  ="xforms-select"  submission  ="update"/>     </  itemset  ></  select1  >     <  table  >       <  tr   repeat-nodeset  ="instance('s')/books/book">       ...</  tr  > </  table  ></  body  ></  html  > 

Notice that this usage is similar to the automated profile lookup demonstrated in Figure 7.1.

These events are also raised when the user changes the selected case in interacting with a conditional interface created via construct switch (see Section 4.2). In this situation, the selected case receives event xforms-select ; the previously selected case receives event xforms-deselect . XForms authors can use this to attach additional custom behavior to such dynamic interfaces; as an example, a speech-enabling extension might trigger a spoken message that speaks the label of the case that got selected.

8.4.3 Interacting with Repeat Collections

User interaction with repeating structures can directly affect the underlying collection by the addition or deletion of nodes. Nodes are added and deleted by actions insert and delete ; events xforms-insert and xforms-delete are notification events raised by these actions. These events are targeted at the instance affected by the insert or delete operation. They carry the XPath locator of the node to operate on as part of the context information. These events are allowed to bubble to enable centralized handling of these notifications; this means that the XForms author can attach a single custom action handler at the model that notifies the user about all insertions and deletions that affect any contained instance in the model .

User interaction with repeat structures can also change the portion of the underlying collection that is presented; notification events xforms-scroll-first and xforms-scroll-last are raised when the user attempts to scroll off either end of the collection. These events are targeted at the repeat and can be canceled or allowed to bubble . As an example, an accessibility aid might use these events to attach an action that produces an audible cue when the user hits either end of the collection.

8.4.4 Listening for Changes in State

Notification events enumerated in this section are raised in response to changes of state in the instance data. Such changes of state reflect updated values of the various model properties introduced in Chapter 5. We detailed the CSS pseudoclasses that can be used explicitly to style user interface controls based on the state of these properties in Table 5.1. There is a one-to-one correspondence between these pseudoclasses and the notification events that are raised in response to changes in state. All of these events are targeted at the affected user interface control and can be either canceled or allowed to bubble . XForms authors can use these notification events to attach custom behavior that extends beyond merely styling user interface controls.

Table 8.1. Notification Events that Signal State Changes

Notification	CSS Pseudoclass
xforms-out-of-range	:out-of-range
xforms-in-range	default
xforms-valid	:valid
xforms-invalid	:invalid
xforms-readonly	:readonly
xforms-readwrite	:readwrite
xforms-required	:required
xforms-optional	:optional
xforms-enabled	:enabled
xforms-disabled	:disabled

8.4.5 Submit Notifications

We conclude our roundup of notification events with xforms-submit-done and xforms-submit-error . As their names imply, these are raised to indicate the result of submit processing. Successful completion, including interpretation of the server response as specified by the corresponding submission element raises event xforms-submit-done . It is targeted at element submission , and it can be either canceled or allowed to bubble . Error during submit processing raises event xforms-submit-error ; the event is targeted at the model containing the submission that failed, with the context information supplying details on the method that failed.

We conclude this section with a summary of how XForms events relate to the various XForms actions defined in Chapter 7 by giving the complete mapping between the declarative XForms actions and the XForms events they dispatch in Table 8.2.