10.1.1 The action Element

This action causes its child actions to be invoked in the order that they are specified in the document.

Common Attributes: Common, Events

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

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

Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes.

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

Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes.

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

Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes.

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

Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes.

10.1.7 The setfocus Element

This action dispatches an xforms-focus event (4.3.2 The xforms-focus Event) to the element identified by attribute control. 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. If this attribute is missing, a default value of "replace" is assumed.

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 evaluation context for this XPath expression is the result from the Single Node Binding.

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:

<setvalue bind="put-here" value="a/b/c"/>

<setvalue bind="put-here">literal string</setvalue>

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.

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.

<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

Optional XForms Model selector, as defined in 3.2.3 Single-Node Binding Attributes.

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>

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>

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>

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.