1 Introduction
This document describes the Actions Module, which includes a
collection of elements and attribute groups that provides XML
languages with the ability to uniformly integrate XML Event handlers
that capture high-level semantics that can be invoked in response to
events. As a consequence, it significantly enhance the accessibility
of applications that use this syntax in comparison to previous Web
technologies that relied exclusively on scripting.
This document uses the terms
must
,
must not
,
required
,
shall
,
shall not
,
recommended
,
should
,
should not
,
may
, and
optional
in accord with
[RFC 2119]
.
2 The Action module
This module defines the Action content set, the action action and the dispatch actions.
Both actions are added to the Action content set. When other modules define actions, they should also add their actions the Action content set.
| Element | Attributes | Minimal Content Model |
|---|
| Action& | | action, dispatch |
|
action
|
Common
,
Events
,
Action Common
|
(
Action
)
*
|
|
dispatch
|
Common
,
Events
,
Action Common
, name (xsd:NMTOKEN), target (xsd:IDREF), delay
(xsd:nonNegativeInteger), bubbles (xsd:boolean), cancelable
(xsd:boolean)
| name?, target?, delay? [in any order] |
For each action, a module should define the following properties:
Name
Common Attributes
Special Attributes
Description of behavior
Additionally this module introduces the following two Attribute collections:
| Collection Name | Attributes in Collection |
|---|
| Action Common |
if
(boolean XPath Expression),
while
(boolean XPath Expression)
|
| Events | all of the "global" attributes defined in the [XML Events] specification. |
The Action Common attribute group contains attributes for 2.3 Conditional Execution of Actions and 2.4 Iteration of Actions.
The Event attribute group includes all of the "global" attributes defined in the [XML Events] specification.
The following example shows how events can be used:
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.
All the action elements should explicitly allow global attributes from the XML Events namespace, and apply the processing defined in that specification in section 2.3 [XML Events].
2.1 The action Element
This action causes its child actions to be invoked in the
order that they are specified in the document. The action element is added to the Action content set.
Common Attributes:
Common
,
Events
,
Action Common
Grouping Actions
<trigger>
<label>Click me</label>
<action ev:event="DOMActivate">
<reset model="thismodel"/>
<setvalue ref="."/>
</action>
</trigger>
2.2 The dispatch Element
This action dispatches an XML Event to a specific target element. 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 the module that introduces the event 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, Action Common
Special Attributes:
- name
Optional name of the event to dispatch.
- target
Optional reference to the event target.
- delay
Optional attribute that indicates the minimum number of milliseconds to delay dispatching of the event to the target.
The default is the empty string, which indicates no delay.
- bubbles
Optional boolean indicating if this event bubbles—as defined in [DOM2 Events]. The default value is true for 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 is true for a custom event. For predefined events, this attribute has no effect.
The event to be dispatched is given by the name attribute or the name child element.
Due to the addition of the name element, the name attribute is not required, but either the name attribute or the name element must appear.
If the event name is not specified or empty string, then this action has no effect.
The element to which the event is to be dispatched is identified by the target attribute or the target
child element. Due to the addition of the target element, the target attribute is not required, but either the target attribute or the
target element must appear. If no such element contains the target identifier, then this action has no effect.
| Editorial note: Nick Van den Bleeken | 2007-07-08 |
| Removed ID resolve text for repeats, this should be added in the module that introduces repeats |
The event may be dispatched immediately or after a specified non-negative number of milliseconds of delay. The event delay is specified
the delay attribute or by the child element delay.
If the delay is not specified or if the given value does not conform to xsd:nonNegativeInteger, then the event is dispatched
immediately as the result of the dispatch action.
Otherwise, the specified event is added to the delayed event queue
unless an event with the same name and target element already exists on the delayed event queue. The dispatch
action has no effect if the event delay is a non-negative integer and the specified event is already in the delayed event queue.
| Editorial note: Nick Van den Bleeken | 2007-07-08 |
| Removed "Since an element bearing a particular ID may be repeated, the delayed event queue may contain more than one
event with the same name and target IDREF. It is the name and the target run-time element that must be unique." this should be added in the module that introduces repeats |
If a run-time element is destroyed, then any delayed events targeted at that element are removed from the delayed event queue.
A run-time element may be destroyed for a number of reasons, including shutdown.
As soon as possible after the specified delay in milliseconds has elapsed, the event is removed from the delayed event queue and then dispatched.
In the same manner used to handle user-generated events or the completion of an asynchronous submission, the dispatch and processing
of delayed events is done without interrupting the processing of another event and its event handlers.
Note:
Because the delayed event is first removed from the delayed event queue and then dispatched, a handler for a given
event may dispatch the event again with a delay. This can be used to perform simple polling and asynchronous looping
operations. Moreover, the if attribute can be applied to the dispatch action to decide when to
discontinue the polling or looping based on a setting in instance data.
2.2.1 The name Child Element
This section defines a new child element of dispatch that provides an alternate
means of specifying the name of the event to dispatch.
Element: name
Common attributes: None
Special Attributes:
- value
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
event name, the result of the expression is processed as if by call to the XPath string function.
An empty string is used if the XPath evaluation fails.
Content: PCDATA
The event name of the dispatch action is given by the name attribute or the name element.
If both are given, the element takes precedence.
The name element can provide the event name with either its string content or the value attribute.
If both are given, then the value attribute takes precedence.
2.2.2 The target Child Element
This section defines a new child element of dispatch that provides an alternate means of specifying the
target of the event to be dispatched.
Element: target
Common attributes: None
Special Attributes:
- value
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
event target, the result of the expression is processed as if by call to the XPath string function.
An empty string is used if the XPath evaluation fails.
Content: PCDATA
The event target of the dispatch action is given by the target attribute or the target element.
If both are given, the element takes precedence.
The target element can provide an IDREF for the event target with either its string content or the value attribute.
If both are given, then the value attribute takes precedence.
2.2.3 The delay Child Element
This section defines a new child element of dispatch that provides an alternate means of specifying the
delay imposed on the event to be dispatched.
Element: delay
Common attributes: None
Special Attributes:
- value
Optional attribute containing an XPath expression to evaluate using the in-scope evaluation context. To obtain the
event delay, the result of the expression is processed as if by call to the XPath string function. If
the result does not conform lexically to xsd:nonNegativeInteger, then the result of empty string is used.
An empty string is used if the XPath evaluation fails.
Content: PCDATA
The event delay of the dispatch action is given by the delay attribute or the delay element.
If both are given, the element takes precedence. The delay element can provide the delay with either its string content or the value attribute.
If both are given, then the value attribute takes precedence.
2.3 Conditional Execution of Actions
The if attribute can optionally be added to any action. It contains an [XPath 1.0] expression
that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is
converted to a boolean as if converted with the boolean() function defined by the
[XPath 1.0] specification.
If the converted result of the expression evaluates to false, then the action is not performed. If the
converted result is true, then the action is performed.
If this attribute is applied to an action element and the converted result of evaluation is
false, then all of the actions within the action element are omitted from the execution
of the action sequence that invoked the action element. If the result is true,
then the contained actions are performed according to the normal processing rules such as deferred update behavior
and applicability of conditional and iterative attributes.
| Editorial note: Nick Van den Bleeken | 2007-07-08 |
Move "In actions insert and delete, the attribute context is evaluated before the if attribute." to Binding Attributes Module |
Automatic Focus Advancement
The setfocus action in each input control is executed only if the node bound to the control
is a number of a particular length. The exacting form author could perform further validity tests.
...
<input ref="areaCode" id="AreaCodeControl" incremental="true">
<label>Area Code</label>
<setfocus ev:event="xforms-value-changed" control="ExchangeControl" if="string-length(.)=3 and . > 0"/>
</input>
<input ref="exchange" id="ExchangeControl" incremental="true">
<label>Exchange</label>
<setfocus ev:event="xforms-value-changed" control="LocalControl" if="string-length(.)=3 and . > 0"/>
</input>
<input ref="local" id="LocalControl" incremental="true">
<label>Local</label>
<setfocus ev:event="xforms-value-changed" control="ExtensionControl" if="string-length(.)=4 and . > 0"/>
</input>
...
Handling Focus for Empty Repeats
The trigger that performs a delete conditionally sets the focus to a control outside of the repeat if
the repeat becomes empty due to the deletion. The setfocus is called first because the
delete removes the context node.
...
<trigger id="InsertControl">
<label>Insert Row</label>
<action ev:event="DOMActivate">
<insert context="purchaseOrder/lines" nodeset="line"
at="index('PurchaseOrderRepeat')" origin="instance('prototype')"/>
<setfocus control="PurchaseOrderRepeat"/>
</action>
</trigger>
<repeat nodeset="purchaseOrder/lines/line" id="PurchaseOrderRepeat">
...
<trigger>
<label>Delete Row</label>
<action ev:event="DOMActivate">
<setfocus control="InsertControl" if="last()=1"/>
<delete nodeset="../line" at="index('PurchaseOrderRepeat')"/>
</action>
</trigger>
...
</repeat>
2.4 Iteration of Actions
The while attribute can optionally be added to any action. It contains an [XPath 1.0] expression
that is evaluated using the in-scope evaluation context before the action is executed. The result of the expression is
converted to a boolean as if converted with the boolean() function defined by the
[XPath 1.0] specification.
If the converted result of the expression is true, then the action is performed and then the
expression is re-evaluated. The action is executed repeatedly until the converted result of the expression
evaluates to false.
If this attribute is applied to an action element, then the sequence of actions in its content are
executed repeatedly once for each time the immediately preceding evaluation of the expression yields a result of true.
When actions are iteratively executed, they are still subject to the normal action processing rules such as deferred
update and applicability of conditional and iterative attributes.
An action may be executed zero times due to this attribute. Furthermore, if an action bears this attribute and the
if attribute, then the expressions of both attributes must evaluate to true before each iterative
execution of the action.
| Editorial note: Nick Van den Bleeken | 2007-07-08 |
Move "In actions insert and delete, the attribute context is evaluated before the while attribute." to Binding Attributes Module |
Summing Selected Results
Counter and accumlator variables are created in instance data to sum a selection of values chosen by the user
<trigger>
<label>Get Sum</label>
<action ev:event="DOMActivate">
<setvalue ref="instance('temps')/counter" value="1"/>
<setvalue ref="instance('temps')/accumulator" value="0"/>
<action while="instance('temps')/counter <= count(/some/nodes)">
<setvalue ref="instance('temps')/accumulator"
value=". + instance('default')/some/nodes[number(instance('temps')/counter)]"
if="boolean-from-string(/some/nodes[number(instance('temps')/counter)]/@selected)"/>
<setvalue ref="instance('temps')/counter" value=". + 1"/>
</action>
</action>
</trigger>
2.5 The event() Function
object event(string)
Function event returns context specific information determined by the string
argument. The returned context information is an XPath object whose type and content
depends upon the requested property. Each event describes what properties can be accessed by this function
and the type and value that will be returned as the result.
The event context properties available for each event are provided in the sections that describe the events.
This function is intended for use in the XPath expressions of XForms actions. If invoked for any other
XPath expression this function returns the empty string. If this function is invoked from an XPath expression for an XForms action, then event context
information is used from the most recently dispatched event whose action handler contains the XForms action.
Some properties defined for an event may be unavailable if certain prerequisite conditions were not met prior to the event being dispatched.
Implementations may also add custom properties. If the event context information does not contain the property indicated by the
string argument, then an empty node-set is returned.
Examples:
If called from an xforms-insert event handler, a string is returned containing the attribute value of the nodeset or bind attribute used by the insert action.
If called from an xforms-link-exception or xforms-link-error event handler, a string is returned containing the URI of the failed link.