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 ProcessingThe 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
7.3.2 Useful EventsFollowing 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:
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.
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.
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.
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.
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.
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.
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.
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.
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.
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]
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.
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.
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.
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.
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.
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.
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 EventsThe following XForms events are included here for completeness, even though they are not very useful for form authors.
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.
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 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 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.
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.
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.
These events initiate the processing needed to add or remove nodes from repeating sets, and serve primarily as bookkeeping events for XForms.
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.
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 HandlingInevitably, 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.
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.
This event indicates that the submit process failed to successfully complete.
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.
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.
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.
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. |