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 10.1.13 Actions insert, delete and setindex |
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.
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:
<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].
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.
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 case the bubbles
and cancelable
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.
Common Attributes: Common, Events
Special Attributes:
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]. The default value depends on the definition of a custom event. For predefined events, this attribute has no effect.
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.
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:
Optional XForms Model selector, as 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).
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:
Optional XForms Model selector, as 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).
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:
Optional XForms Model selector, as 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).
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:
Optional XForms Model selector, as 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).
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:
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.
Common Attributes: Common, Events, Single Node Binding (optional)
Special Attributes:
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).
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:
The document is loaded into a new presentation context, e.g., a new window. 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.
Common Attributes: Common, Events, Single Node Binding
Special Attributes:
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"/>
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"
.
<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).
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:
Required reference to a submission
element.
Note:
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 xforms-reset
is defined in the processing model—see 4.3.8 The xforms-reset Event.
Common Attributes: Common, Events
Special Attributes:
Optional XForms Model selector, as 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).
This action encapsulates a message to be displayed to the user.
Common Attributes: Common, Events, Single Node Binding (optional)
Special Attributes:
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, 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>
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.
Table of Contents | Top |