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 XForms 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.
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 targetid attribute or the targetid chlid element. Due to the addition of the targetid element, the targetid attribute is not required, but this action has no effect unless the target identifier is specified by the element or attribute.
For backwards compatibility with documents created for earlier versions of the specification, the attribute named target and the child element target are allowed to be used as well. The attribute and element named target provide exactly the same behaviors as the targetid attribute and element, except that the target attribute and element are ignored if the dispatch element also bears a targetid attribute or contains a targetid child element.
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.
Example
| XML |
Copy Code
|
|---|---|
<xforms:action ev:event="DOMActivate"> <xforms:dispatch name="xforms-rebuild" targetid="mymodel"/> </xforms:action> |
|
Attributes
| Name | Required / optional | Description |
|---|---|---|
| name | optional | Attribute for specifying the name of the event to dispatch. |
| targetid | optional | Attribute for specifying the 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 | Attribute containing a boolean indicating if this event bubbles - as defined in DOM2 Events specification. The default value is true for a custom event. For predefined events, this attribute has no effect. |
| cancelabe | optional | Attribute containing a boolean indicating if this event is cancelable - as defined in DOM2 Events specification. The default value is true for a custom event. For predefined events, this attribute has no effect. |
| Common Attributes | optional | Any attribute from the Common Attributes collection (e.g. id). |
| XML Events | optional | Any attribute from the XML Events collection (e.g. ev:event) |
| Common Action Attributes | optional | Any attribute from the Common Action Attributes collection (if or while) |
Content
Within an dispatch element, the following child elements are allowed:
| Element Name | Required / optional | Description |
|---|---|---|
| name | optional | The event name of the dispatch action is given by the name attribute or the name element. |
| targetid | optional | The event target of the dispatch action is given by the targetid attribute or the targetid element. |
| delay | optional | The event delay of the dispatch action is given by the delay attribute or the delay element. |
Specification
Link to the XForms specification: the dispatch element.