10 XForms Actions

This chapter defines an XML Events-based [XML Events] common set of actions that can be invoked in response to events.

Note:

XForms itself defines no method for script-based event handling. The definition of such facilities is a responsibility of the hosting language.

10.1 The XForms Action Module

All form controls defined in this specification have a set of common behaviors that encourage consistent authoring and look and feel for XForms-based applications. This consistency comes from attaching a common set of behaviors to the various form controls. In conjunction with the event binding mechanism provided by XML Events, these handlers provide a flexible means for forms authors to specify event processing at appropriate points within the XForms user interface. XForms Actions are declarative XML event handlers that capture high-level semantics. As a consequence, they significantly enhance the accessibility of XForms-based applications in comparison to previous Web technologies that relied exclusively on scripting.

The elements and attributes included in this module are:

Element Attributes Minimal Content Model
action Common, Events (Action)+
dispatch Common, Events, name (xsd:NMTOKEN), target (xsd:IDREF), bubbles (xsd:boolean), cancelable (xsd:boolean) EMPTY
rebuild Common, Events, model (xsd:IDREF) EMPTY
recalculate Common, Events, model (xsd:IDREF) EMPTY
revalidate Common, Events, model (xsd:IDREF) EMPTY
refresh Common, Events, model (xsd:IDREF) EMPTY
setfocus Common, Events, control (xsd:IDREF) EMPTY
load Common, Events, Single Node Binding (optional), resource (xsd:anyURI), show ("new" | "replace") EMPTY
setvalue Common, Events, Single Node Binding, value (XPathExpression) PCDATA
send Common, Events, submission (xsd:IDREF) EMPTY
reset Common, Events, model (xsd:IDREF) EMPTY
message Common, Events, Single Node Binding (optional), Linking, level ("ephemeral" | "modeless" | "modal") (PCDATA|UI Inline)*

See also: 9.2.3 The toggle Element; 9.3.5 The insert Element; 9.3.6 The delete Element; and 9.3.7 The setindex Element.

This module also defines the content set "Action", which includes the following elements (of these, toggle comes from the XForms Switch module, and insert, delete, and setindex come from the XForms Repeat module):

(action|dispatch|rebuild|refresh|recalculate|revalidate|setfocus|
 load|setvalue|send|reset|message|toggle|insert|delete|setindex)*

Additionally, this module defines the attribute group "XML Events", which includes all of the "global" attributes defined in that specification ([XML Events]).

The following example shows how events can be used:

Example: Action Syntax
<xforms:trigger>
  <xforms:label>Reset</xforms:label>
  <xforms:reset ev:event="DOMActivate" model="thismodel"/>
</xforms:trigger>

This example recreates the behavior of the HTML reset control, which this specification does not define as an independent form control.

For each built-in XForms Action, this chapter lists the following:

Name
Common Attributes
Special Attributes
Description of behavior

All elements defined in this chapter explicitly allow global attributes from the XML Events namespace, and apply the processing defined in that specification in section 2.3 [XML Events].

10.1.1 The action Element

Action action is used to group multiple actions.

When using element action to group actions, care should be taken to list the event on element action, rather than on the contained actions.

Common Attributes: Common, Events

Example: Grouping Actions
<trigger>
  <label>Click me</label>
  <action ev:event="DOMActivate">
    <reset model="thismodel"/>
    <setvalue ref="."/>
  </action>
</trigger>

Notice that in the above example, ev:event="DOMActivate" occurs on element action. Placing ev:event="DOMActivate" on either or both of the contained actions will have no effect. This is because the above example relies on the defaulting of [XML Events] attributes observer and handler. As defined in the XML Events specification, if both observer and handler attributes are omitted, then the parent is the observer. Placing ev:event="DOMActivateD" on the children of element action therefore causes element action to become the observer for the individual events. Consequently, these actions will never be triggered since events arrive at element trigger, not element action.

Deferred Updates: Many XForms Actions have a deferred effect on the instance data when specified as a descendant of an action element.

Implementations are free to use any strategy to accomplish deferred updates, but the end result must be as follows: Instance data changes performed by a set of actions do not result in immediate computation dependency rebuilding, recalculation, revalidate and form control refreshing until the termination of the outermost action handler, as described here. Each outermost action handler can be thought of as having a set of Boolean flags, initially false, to indicate whether each of the actions rebuild, recalculate, revalidate, and refresh are required upon termination of the outer action handler.

Actions that directly invoke rebuild, recalculate, revalidate, or refresh always have an immediate effect, and clear the corresponding flag. The XForms Actions in this category are:

rebuild
recalculate
revalidate
refresh

XForms Actions that change the tree structure of instance data result in setting all four flags to true. The XForms Actions in this category are:

insert
delete

XForms Actions that change only the value of an instance node results in setting the flags for recalculate, revalidate, and refresh to true and making no change to the flag for rebuild. The XForms Actions in this category are:

setvalue

Finally, the reset action takes effect immediately and clears all of the flags.

10.1.2 The dispatch Element

This action dispatches an XForms Event to a specific element identified by the target attribute. Two kinds of event can be dispatched:

  1. Predefined XForms events (i.e., xforms-event-name), in which case the bubbles and cancelable attributes are ignored and the standard semantics as defined in 4 Processing Model apply.

  2. An event created by the XForms author with no predefined XForms semantics and as such not handled by default by the XForms Processor.

Common Attributes: Common, Events

Special Attributes:

name

Required name of the event to dispatch.

target

Required reference to the event target.

bubbles

Optional boolean indicating if this event bubbles—as defined in [DOM2 Events]. The default value depends on the definition of a custom event. For predefined events, this attribute has no effect.

cancelable

Optional boolean indicating if this event is cancelable—as defined in [DOM2 Events]. The default value depends on the definition of a custom event. For predefined events, this attribute has no effect.

10.1.3 The rebuild Element

This action causes the processing of xforms-rebuild to happen, bypassing the normal event flow. This action results in the XForms Processor rebuilding any internal data structures used to track computational dependencies among instance data nodes —see 4.3.7 The xforms-rebuild Event.

Common Attributes: Common, Events

Special Attributes:

model

Required IDREF of the model to be processed.

Note:

If this action is contained within an action element, it has special deferred update behavior (10.1.1 The action Element).

10.1.4 The recalculate Element

This action causes the processing of xforms-recalculate to happen, bypassing the normal event flow. As a result, instance data nodes whose values need to be recalculated are updated as specified in the processing model—see 4.3.6 The xforms-recalculate Event.

Common Attributes: Common, Events

Special Attributes:

model

Required IDREF of the model to be processed.

Note:

If this action is contained within an action element, it has special deferred update behavior (10.1.1 The action Element).

10.1.5 The revalidate Element

This action causes the processing of xforms-revalidate to happen, bypassing the normal event flow. This results in the instance data being revalidated as specified by the processing model—see 4.3.5 The xforms-revalidate Event.

Common Attributes: Common, Events

Special Attributes:

model

Required IDREF of the model to be processed.

Note:

If this action is contained within an action element, it has special deferred update behavior (10.1.1 The action Element).

10.1.6 The refresh Element

This action causes the processing of xforms-refresh to happen, bypassing the normal event flow. This action results in the XForms user interface being refreshed, and the presentation of user interface controls being updated to reflect the state of the underlying instance data—see 4.3.4 The xforms-refresh Event.

Common Attributes: Common, Events

Special Attributes:

model

Required IDREF of the model to be processed.

Note:

If this action is contained within an action element, it has special deferred update behavior (10.1.1 The action Element).

10.1.7 The setfocus Element

This action sets focus to the form control identified by attribute control by dispatching an xforms-focus event (4.3.2 The xforms-focus Event). Note that this event is implicitly invoked to implement XForms accessibility features such as accesskey.

Common Attributes: Common, Events

Special Attributes:

control

Required reference to a form control.

Setting focus to a repeating structure sets the focus to the repeat item represented by the repeat index.

10.1.8 The load Element

This action traverses the specified link.

Common Attributes: Common, Events, Single Node Binding (optional)

Special Attributes:

resource

Link to external resource to load, defined as an [XLink 1.0] link between this element and the remote resource indicated. No XLink actuate value is defined, since control of actuation is defined by XML Events. The XLink show value depends on the show attribute. If the link traversal fails, it is treated as an error (4.5.3 The xforms-link-error Event).

show

Optional link behavior specifier.

Either the single node binding attributes, pointing to a URI in the instance data, or the linking attributes are required. If both are present, the action has no effect.

Possible values for attribute show have the following processing for the document (or portion of a document) reached by traversing the link:

new

The document is loaded into a new presentation context, e.g., a new window. Form processing in the original window continues.

replace

The document is loaded into the current window. Form processing is interrupted, exactly as if the user had manually requested navigating to a new document.

10.1.9 The setvalue Element

This action explicitly sets the value of the specified instance data node.

Common Attributes: Common, Events, Single Node Binding

Special Attributes:

value

Optional XPath expression to evaluate, with the result stored in the selected instance data node.

The element content of setvalue specifies the literal value to set; this is an alternative to specifying a computed value via attribute value. The following two examples contrast these approaches:

Example: setvalue with Expression
<setvalue bind="put-here" value="a/b/c"/>

This causes the string value at a/b/c in the instance data to be placed on the single node selected by the bind element with id="put-here".

Example: setvalue with Literal
<setvalue bind="put-here">literal string</setvalue>

This causes the value "literal string" to be placed on the single node selected by the bind element with id="put-here".

If neither a value attribute nor text content are present, the effect is to set the value of the selected node to the empty string (""). If both are present, the value attribute is used.

All strings are inserted into the instance data as follows:

  • Element nodes: If the element has any child text nodes, the first text node is replaced with one corresponding to the new value. If no child text nodes are present, a text node is created, corresponding to the new value, and appended as the first child node.

  • Attribute nodes: The string-value of the attribute is replaced with a string corresponding to the new value.

  • Text nodes: The text node is replaced with a new one corresponding to the new value.

  • Namespace, processing instruction, comment, and the XPath root node: behavior is undefined.

Note:

If this action is contained within an action element, it has special deferred update behavior (10.1.1 The action Element).

10.1.10 The send Element

This action initiates submit processing by dispatching an xforms-submit event. Processing of event xforms-submit is defined in the processing model—see 4.3.9 The xforms-submit Event.

Common Attributes: Common, Events

Special Attributes:

submission

Required reference to a submission element.

Note:

This XForms Action is a convenient way of expressing the following:

<dispatch target="mysubmitinfo" name="xforms-submit"/>

10.1.11 The reset Element

This action initiates reset processing by dispatching an xforms-reset event to the specified model. Processing of event xforms-reset is defined in the processing model—see 4.3.8 The xforms-reset Event.

Common Attributes: Common, Events

Special Attributes:

model

Required selection of instance data for reset, defined in 3.2.3 Single-Node Binding Attributes.

Note:

If this action is contained within an action element, it has special deferred update behavior (10.1.1 The action Element).

10.1.12 The message Element

This action encapsulates a message to be displayed to the user.

Common Attributes: Common, Events, Single Node Binding (optional)

Special Attributes:

Linking Attributes

Link to external message. If the link traversal fails, it is treated as an error (4.5.3 The xforms-link-error Event).

level

Required message level identifier, one of ("ephemeral"|"modeless"|"modal"|QName-but-not-NCName). This specification does not define behavior for QName values.

The message specified can exist in instance data, in a remote document, or as inline text. If more than one source of message is specified in this element, the order of precedence is: single node binding attributes, linking attributes, inline text.

A graphical browser might render a modal message as follows:

<model>
  <message level="modal" ev:event="xforms-ready">This is not a drill!</message>
  ...
</model>

An alert popup, with a helpful error message.

A modeless message is the foundation for displaying a help message, which a graphical browser might render as follows:

<secret ref="/login/password">
  <label>Password</label>
  <help>Have you forgotten your password? Simply call 1-900-555-1212 and have
        a major credit card handy.</help>
</secret>

A password entry form control, with a popup window below, displaying instructions for retrieving a forgotten password

An ephemeral message is the foundation for displaying a hint message, which a graphical browser might render as follows:

<input ref="po/address/street1">
  <label>Street</label>
  <hint>Please enter the number and street name</hint>
</input>

An average-looking text entry form control, with a mouse pointer visible and a tooltip below, reading 'Please enter the number and street name'

10.1.13 Actions insert, delete and setindex

In addition to the action handlers detailed in this chapter, XForms defines three actions as part of the XForms Repeat module: 9.3.5 The insert Element, 9.3.6 The delete Element, and 9.3.7 The setindex Element.