|Table of Contents||Prev||Next||Bottom|
Quick Table of Contents
|10 XForms Actions
10.1 The XForms Action Module
10.1.1 The action Element
10.1.2 The dispatch Element
10.1.3 The rebuild Element
10.1.4 The recalculate Element
10.1.5 The revalidate Element
10.1.6 The refresh Element
10.1.7 The setfocus Element
10.1.8 The load Element
10.1.9 The setvalue Element
10.1.10 The send Element
10.1.11 The reset Element
10.1.12 The message Element
This chapter defines an XML Events-based [XML Events] common set of actions that can be invoked in response to events.
XForms itself defines no method for script-based event handling. The definition of such facilities is a responsibility of the hosting language.
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|
|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, Linking, show ("new" | "replace" | "embed" | "other" | "none")||EMPTY|
|setvalue||Common, Events, Single Node Binding, value (xsd:string)||PCDATA|
|send||Common, Events, submission (xsd:IDREF)||EMPTY|
|reset||Common, Events, model (xsd:IDREF)||EMPTY|
|message||Common, Events, Single Node Binding, Linking, level ("ephemeral" | "modeless" | "modal")||(PCDATA|ANY)*|
This module also defines the content set
"Action", which includes the following elements (of these,
toggle comes from the XForms Switch module, and
come from the XForms Repeat module):
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:
<xforms:trigger> <xforms:label>Reset</xforms:label> <xforms:reset ev:event="xforms-activate" 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:
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].
action is used to group multiple
When using element
action to group actions, care
should be taken to list the event on element
rather than on the contained actions.
<trigger> <label>Click me</label> <action ev:event="xforms-activate"> <reset model="thismodel"/> <setvalue ref="."/> </action> </trigger>
Notice that in the above example,
ev:event="xforms-activate" occurs on element
ev:event="xforms-activate" 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
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="xforms-activate" on the children of element
action therefore causes element
become the observer for the individual actions.
Consequently, these actions will never be triggered since events
arrive at element
trigger, not element
Deferred Updates: Many XForms Actions have a deferred
effect on the instance data when specified as a descendant of an
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,
false, to indicate whether each of the
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:
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:
XForms Actions that change only the value of an instance node
results in setting the flags for
true and making no change to the flag for
rebuild. The XForms Actions in this category are:
reset action takes effect immediately
and clears all of the flags.
This action dispatches an XForms Event to a specific element
identified by the
target attribute. Two kinds of event
can be dispatched:
Predefined XForms events (i.e., xforms-event-name), in which
attributes are ignored and the standard semantics as defined in 4 Processing Model apply.
An event created by the XForms author with no predefined XForms semantics and as such not handled by default by the XForms Processor.
Required name of the event to dispatch.
Required reference to the event target.
Optional boolean indicating if this event bubbles—as defined in DOM2 events.
Optional boolean indicating if this event is cancelable—as defined in DOM2 events.
This action dispatches an
xforms-rebuild event to a
specific XForms Model. 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
This action dispatches an
to a specific XForms Model. 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
This action dispatches an
to a specific XForms Model. This results in the instance data being
revalidated as specified by the processing model—see 4.3.5 The xforms-revalidate
This action dispatches an
xforms-refresh event to a
specific XForms Model. 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
This action sets focus to the form control referenced by the
idref attribute 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
Required reference to a form control.
Setting focus to a repeating structure sets the focus to the repeat item represented by the repeat index.
This action traverses the specified link.
Link to external resource to load. If the link traversal fails, it is treated as an error (4.5.3 The xforms-link-error Event).
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:
The document is loaded into a new window (or other presentation context). Form processing in the original window continues.
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.
This action explicitly sets the value of the specified instance data node.
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"/>
This causes the string value at
a/b/c in the
instance data to be placed on the single node selected by the bind
<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
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
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.
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
Required reference to a
This XForms Action is a convenient way of expressing the following:
<dispatch target="mysubmitinfo" name="xforms-submit"/>
This action initiates reset processing by dispatching an
xforms-reset event to the specified
model. Processing of event
is defined in the processing model—see 4.3.8 The xforms-reset
Required selection of instance data for reset, defined in 3.2.3 Single-Node Binding Attributes.
This action encapsulates a message to be displayed to the user.
Link to external message. If the link traversal fails, it is treated as an error (4.5.3 The xforms-link-error Event).
Required message level identifier.
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 ev:event="xforms-model-initialize">This is not a drill!</message> ... </model>
A modeless message is the foundation for displaying a
help message, which a graphical browser might render
<secret ref="users/currentuser/password"> <label>Please enter your password --it will not be visible as you type.</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
<input ref="po/address/street1"> <label>Street</label> <hint>Please enter the number and street name</hint> </input>
|Table of Contents||Top|