7.3 XForms Events

The XML Events specification provides a clean declarative way to call out actions that should be performed under certain conditions. Under what conditions, exactly? That depends on a processing model including the definition of what events are involved, and when they become active.

At the time of this writing, the topic of XML processing models was still under fervent discussion in various pockets of standards activity, with no obvious end in sight. Each XML specification contains details of its own self-contained processing model, but nowhere is there a description of how different specifications interact or relate to one another. XForms is no different.

An entire chapter in the XForms specification is devoted to the processing model. Much of this material, however, is mainly of interest to programmers who happen to be implementing an XForms support in some product. For form authors, a simpler view is possible.

7.3.1 Stages of XForms Processing

The life-cycle of an XForms processor can be divided into several categories, which is a useful viewpoint for a form author. By scrutinizing what you want to accomplish, you can narrow down the potentially huge list of events to a more manageable list. Figure 7-3 shows the stages of XForms processing.

Figure 7-3. Stages of XForms processing
figs/xfe_0703.gif
Initialization

Obviously, the first step is to initialize all the machinery underlying XForms. In true committee style, the initialization process was extensively discussed, the main decision point being how much stuff gets initialized before versus after the event happens. To make everybody happy, no fewer than three separate initialization events were defined, some of which fire multiple times.

Interaction

The major portion of XForms processing involves interacting with the user, to the end of producing an XML document. During interaction, two different kinds of events are important: events that provide a notification that something happened, and events that cause something to happen. Both kinds of events are important to form authors.

Submit

Sending the form data on its way is the goal of most forms, at least in theory. In practice, the submission attempt might not get very far, such as when the form contains invalid data. Other problems too, such as a crashed server, can prevent the submission from completing. For this reason, the submission process includes extra events that help the form author determine whether the submission was successful.

Deinitialization

In HTML forms, submitting the form and loading a new page always happened at the same time. In XForms, however, the author has more granular control of the process. Thus, even though there is a single deinitialization event, it's still worth discussion of when it happens.

Error Condition

Error processing is a tricky subject. In HTML forms, nearly any error is tolerated without generating error messages (but often at the expense of erratic or unpredictable behavior). In XForms, any number of problems can cause a fatal error, which will prevent a form from displaying properly.

7.3.2 Useful Events

Following the approach in Chapter 4, the following sections categorize events into the useful and (politely) less-useful categories. Most of these events come from the XForms specification, but a few truly useful ones come from other places. Events are one of four major types:

lifecycle

An event that deals with setting up or tearing down the XForms engine.

notification

An event indicating something took place.

interaction

An event that triggers some kind of processing. Cancelling the event (when that is possible) stops the default processing.

error handling

An event indicating an error or some other unusual situation occurred.

Another important part of the description of an event is whether it bubbles, and whether it is cancelable, in terms of XML Events. Each event description contains all of the preceding information.

The DOMActivate Event

Event type: (From DOM Level 2 Events)
Event target element: form control, possibly other elements such as hyperlinks
Bubbles: Yes
Cancelable: Yes

DOMActivate is probably the event most commonly used by XForms authors. Activation in this context can mean a mouse click, pressing the Enter key, or any other action indicating the user has requested that something special should happen.

Even though a DOM isn't guaranteed to be present in an XForms engine, this event will always work as described here.

The DOMFocusIn and DOMFocusOut Events

Event type: (From DOM Level 2 Events)
Event target element: form control, possibly other elements such as hyperlinks
Bubbles: Yes
Cancelable: No

These two events serve as notifications of receiving and losing focus, respectively. In XForms, they are mainly useful as a way of tracking and coordinating focus changes on form controls.

Even though a DOM isn't guaranteed to be present in an XForms engine, this event will always work as described here.

The xforms-ready Event

Event type: lifecycle
Event target element: model
Bubbles: Yes
Cancelable: No

This event is fired just after the entire XForms processor has been initialized and is ready to go. As such, it's the perfect place to perform any needed initialization as part of startup.

The xforms-model-construct-done Event

Event type: lifecycle
Event target element: model
Bubbles: Yes
Cancelable: No

When "lazy author" processing is used when the XForms processor synthesizes instance data based only on form controls the XForms Model is not yet initialized when this event fires. In practice, this is not a serious problem, since "lazy author" forms are typically very simplistic, and don't use XML Events or XForms Actions at all.

This initialization event occurs after the XForms Model has been initialized, but before the user interface has, making it the perfect place to perform any data-level initialization tasks, before any data shows up in a form control.

The xforms-model-destruct Event

Event type: lifecycle
Event target element: model
Bubbles: No
Cancelable: No

This event is fired as part of the shutdown sequence for the XForms engine. If any of the form logic has allocated temporary resources, this is the place to free them.

The xforms-help and xforms-hint Events

Event type: interaction
Event target element: form control
Bubbles: Yes
Cancelable: Yes

These events indicate that a help or hint message is about to be displayed to the user. It can be useful to perform other processing at this time. It can also be useful in some cases to cancel the event, which will prevent the help or hint from rendering. Finally, it can also be useful to dispatch this event to a form control to provide help or hint on demand.

The xforms-reset Event

Event type: interaction
Event target element: model
Bubbles: Yes
Cancelable: Yes

This event indicates that the form is about to be reset. In some situations, it might be necessary to prevent a reset from happening, in which case the event can be terminated, blocking the reset. Otherwise, a listener for this event is a good chance to do any last-minute processing before everything in the XForms Model resets to its initial state.

The xforms-submit Event

Event type: submission
Event target element: submission
Bubbles: Yes
Cancelable: Yes

This event indicates that the form is about to be submitted. In some situations, it might be necessary to prevent submission from happening, in which case the event can be terminated, blocking the submission. Otherwise, a listener for this event is a good chance to do any last-minute processing before the form data gets packaged and sent over the wire.

The xforms-value-changed Event

Event type: notification
Event target element: form control
Bubbles: Yes
Cancelable: No

This event serves as a notification that the value that a form control is displaying is due for a change. This normally happens at the point where the user navigates away from a changed control, since only then is it known that the user has finalized her choice. In this respect, xforms-value-changed is much like the onchange event from HTML.

It's also possible, however, for a form control to send additional xforms-value-changed events while the user is still interactively typing, clicking, dragging, or speaking to produce a value. In order for these extra events to be generated, the attribute incremental on the form control needs to have the value true.[1]

[1] For the select and select1 form controls, incremental="true" is the default, so the extra events will normally be dispatched as the selection interactively changes.

The xforms-select and xforms-deselect Events

Event type: notification
Event target element: item or case
Bubbles: Yes
Cancelable: No

These events indicate that a particular list item has been selected or deselected. Additionally, within switch elements, individual case elements will be the target of these events as they become selected and deselected.

The xforms-valid and xforms-invalid Events

Event type: notification
Event target element: form control
Bubbles: Yes
Cancelable: No

These events serve as notifications as to whether a form control is valid or invalid, and can be useful when custom error messages or validity feedback are needed. Either of these events will be dispatched only when the validity state of the form control changes.

The xforms-readonly and xforms-readwrite Events

Event type: notification
Event target element: form control
Bubbles: Yes
Cancelable: No

These events serve as notifications as to whether a form control is read-only or read-write. In most forms, every form control will be fixed as either read-only or not. The dynamic nature of the readonly model item property, however, means that the writability of a form control can change pretty much at any time. Either of these events will be dispatched only when the read-only state of the form control changes.

The xforms-required and xforms-optional Events

Event type: notification
Event target element: form control
Bubbles: Yes
Cancelable: No

These events serve as notifications as to whether a form control is required or optional. In most forms, every form control will be fixed as either required or not. The dynamic nature of the required model item property, however, means that the requirement of a form control can change pretty much at any time. Either of these events will be dispatched only when the required state of the form control changes.

The xforms-enabled and xforms-disabled Events

Event type: notification
Event target element: form control
Bubbles: Yes
Cancelable: No

These events serve as notifications as to whether a form control is enabled or disabled, as controlled by the relevant model item property. Normally, a form is designed so that different form controls become relevant on an as-needed basis, which makes this notification especially common and useful. Either of these events will be dispatched only when the relevant state of the form control changes.

The xforms-out-of-range and xforms-in-range Events

Event type: notification
Event target element: form control
Bubbles: Yes
Cancelable: No

These events serve as notifications that a form control isn't able to display the current value for some reason. For example, a range control might only be capable of controlling values between 0 and 100, and yet be bound to a value of 150 in the instance data. select1 controls are also limited to displaying values defined in item or itemset elements, and thus can become out of range when initial values are applied. Either of these events will be dispatched only when the relevant state of the form control changes.

The xforms-submit-done Event

Event type: notification
Event target element: submission
Bubbles: Yes
Cancelable: No

This event is a notification that a form submission has successfully completed. In HTML forms there was no way to tell when (or if) the submission was done, so this event is a welcome addition for form authors.

7.3.3 Less-Useful Events

The following XForms events are included here for completeness, even though they are not very useful for form authors.

The xforms-rebuild, xforms-recalculate, xforms-revalidate, and xforms-refresh Events

Event type: interaction
Event target element: model
Bubbles: Yes
Cancelable: Yes

These events essentially serve bookkeeping purposes for the XForms engine, and receive little use for form authors. xforms-rebuild causes the data structures used for recalculation to be reinitialized, xforms-recalculate performs the actual calculation, xforms-revalidate checks the validity of instance data nodes, and xforms-refresh causes the form controls to reflect the latest condition of the XForms Model. Several notification events provide a better way to keep track of the status of individual form controls: xforms-valid and xforms-invalid, xforms-readonly and xforms-readwrite, xforms-required and xforms-optional, and xforms-enabled & xforms-disabled.

DOM Mouse Events

Event type: (From DOM Level 2 Events)
Event target element: most elements
Bubbles: Yes
Cancelable: Yes (except mousemove)

Mouse events, especially click, should be avoided whenever possible. These events can't be reliably used in XForms, since there's no guarantee that a DOM will be present, or that the device rendering XForms will even have a mouse. Instead, device-independent events, such as DOMActivate, should be used.

DOM Keyboard Events

Event type: (From DOM Level 3 Events)
Event target element: varies
Bubbles: Yes
Cancelable: Yes

DOM Level 2 Events avoided the area of keyboard events. A Working Draft of Level 3 does include key events, but the future of that specification is uncertain. These events can't be reliably used in XForms, however, since there's no guarantee that a DOM will be present, or that the device rendering XForms will even have a keyboard. In general, it is better to use an abstract event, such as DOMActivate, instead of hardware-specific keyboard events.

DOM Mutation Events

Event type: (From DOM Level 2 Events)
Event target element: any element
Bubbles: Yes
Cancelable: No

DOM Mutation Events serve as notifications to various changes in the DOM structure. These events can't be reliably used in XForms, however, since there's no guarantee that a DOM will be present. Instead, more general events such as xforms-value-changed should be used.

The xforms-model-construct Event

Event type: lifecycle
Event target element: model
Bubbles: No
Cancelable: No

This is the first XForms-related event a document will see; it provides the initial hook into XForms Processing. While this event is propagating, nothing is initialized, not even instance data. As such, this event is more useful to XForms implementers than authors.

The xforms-focus Event

Event type: interaction
Event target element: form control
Bubbles: No
Cancelable: Yes

This event causes focus to change to the target form control. Unless you have a specific reason for not using the XForms Action setfocus, this event is generally not needed by form authors. For notifications of focus changing, DOMFocusIn and DOMFocusOut are the best way to keep tabs on focus.

The xforms-insert and xforms-delete Events

Event type: notification
Event target element: instance
Bubbles: Yes
Cancelable: Yes

These events initiate the processing needed to add or remove nodes from repeating sets, and serve primarily as bookkeeping events for XForms.

The xforms-next and xforms-previous Events

Event type: interaction
Event target element: form control
Bubbles: No
Cancelable: Yes

These events indicate the user's intention to navigate forward or backward, relative to the overall navigation order of the form, such as when the Tab key is pressed (though other ways to accomplish navigation are possible, depending on the device in question). There are few useful things that XForms authors can do with these events. DOMFocusIn and DOMFocusOut generally serve as better notifications to keep track of focus.

The xforms-scroll-first and xforms-scroll-last Events

Event type: notification
Event target element: repeat or other element with repeat attributes
Bubbles: Yes
Cancelable: No

Originally, these events were intended to allow repeating items to be dynamically loaded from a database, on demand as the user scrolled through the list. This turned out to be more difficult than it looked. As a result, these events have little use for XForms authors.

7.3.4 Error Handling

Inevitably, problems can happen during form processing. XForms defines events for such situations, with each event categorized as either an error, which is recoverable, or an exception,[2] which is serious enough to immediately terminate form processing with a message.

[2] Those with some programming background might think of an exception as something that can be "caught," in order to prevent a terminating error condition. XForms 1.0, however, doesn't provide any means to catch or re-throw an exception, so they're always fatal.

When an error condition occurs, application-specific handling (such as logging) is always a possibility and, in fact, is a good way to investigate problems.

The xforms-submit-error Event

Event type: error handling
Event target element: model
Bubbles: Yes
Cancelable: No

This event indicates that the submit process failed to successfully complete.

The xforms-binding-exception Event

Event type: error handling
Event target element: any element that can hold a binding expression
Bubbles: Yes
Cancelable: No

This event indicates that some critical problem was found in a binding expression, such as an XPath syntax error, an improperly connected reference from an IDREF to an ID, or duplicated bind elements.

The xforms-link-exception Event

Event type: error handling
Event target element: model
Bubbles: Yes
Cancelable: No

This event indicates that an unrecoverable error occurred when attempting to refer to some external resource. This can happen when an external initial instance fails to load from the src attribute in the instance element.

The xforms-link-error Event

Event type: error handling
Event target element: model
Bubbles: Yes
Cancelable: No

This event indicates that a particular remote resource had a problem, but that processing will continue. Some elements, such as label, can refer to a remote resource and also a local resource as a fallback. When the remote resource fails to load, the local resource will be used instead.

The xforms-compute-exception Event

Event type: error handling
Event target element: model
Bubbles: Yes
Cancelable: No

This event indicates that an unrecoverable error occurred during processing of computes. This can be caused by an XPath syntax error, a circular dependency, or bad parameters to certain XPath functions.



XForms Essentials
Xforms Essentials
ISBN: 0596003692
EAN: 2147483647
Year: 2005
Pages: 117
Authors: Micah Dubinko

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