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

<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.

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.

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.

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.

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:

<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

Required selection of instance data for reset, 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.