XForms/Events Overview
Motivation
[edit | edit source]You want to be able to perform various tasks at various part of the form execution.
Method
[edit | edit source]XForms is integrated with the W3C XML Event standard. This standard creates standard names for almost all of the common events used in the lifecycle of a form. The W3C has attempted to standardize these events and their event labels so that they can be used consistently across browsers from all vendors.
XML Event Types
[edit | edit source]The following is a listing of the XForms events. Some events are tied to individual forms controls such as input, select and textarea and some are tied to the model within the form.
| Event | Cancel | Bubbles | Target |
|---|---|---|---|
| Initialization Events | |||
| xforms-model-construct | N | Y | <model> |
| xforms-model-construct-done | N | Y | <model> |
| xforms-ready | N | Y | <model> |
| xforms-model-destruct | N | N | <model> |
| Processing Events | |||
| xforms-rebuild | Y | Y | <model> |
| xforms-recalculate | Y | Y | <model> |
| xforms-revalidate | Y | Y | <model> |
| xforms-refresh | Y | Y | <model> |
| Interaction Events | |||
| xforms-previous | Y | N | <control> |
| xforms-next | Y | N | <control> |
| xforms-focus | Y | N | <control> |
| xforms-help | Y | Y | <control> |
| xforms-hint | Y | Y | <control> |
| xforms-reset | Y | Y | <model> |
| xforms-submit | Y | Y | <submission> |
| DOMActivate | Y | Y | <control> |
| Notification Events | |||
| DOMFocusIn | N | Y | <control> |
| DOMFocusOut | N | Y | <control> |
| xforms-value-changed | N | Y | <control> |
| xforms-select | N | Y | <item>, <case> or <itemset> |
| xforms-deselect | N | Y | <item>, <case> or <itemset> |
| xforms-scroll-first | N | Y | <repeat> |
| xforms-scroll-last | N | Y | <repeat> |
| xforms-insert | N | Y | <instance> |
| xforms-delete | N | Y | <instance> |
| xforms-valid | N | Y | <control> |
| xforms-invalid | N | Y | <control> |
| xforms-in-range | N | Y | <control> |
| xforms-out-of-range | N | Y | <control> |
| xforms-readonly | N | Y | <control> |
| xforms-readwrite | N | Y | <control> |
| xforms-required | N | Y | <control> |
| xforms-optional | N | Y | <control> |
| xforms-enabled | N | Y | <control> |
| xforms-disabled | N | Y | <control> |
| xforms-submit-done | N | Y | <submission> |
| xforms-submit-error | N | Y | <submission> |
| Error Notifications | |||
| xforms-binding-exception | N | Y | <bind> |
| xforms-link-exception | N | Y | <model> |
| xforms-link-error | N | Y | <model> |
| xforms-compute-exception | N | Y | <model> |
Displaying Events in a Log File
[edit | edit source]One of the best ways to learn about how events get fired is to write them to a log instance and display the log at the bottom of the form. You can do this logging while you are building and debugging your form.
Add the following instance to your model:
<xf:instance xmlns="" id="log">
<events>
<event>log initialized</event>
</events>
</xf:instance>
Whenever you want to see an event, just add an action that appends an event to the end of the log:
<xf:action ev:event="xforms-deselect">
<xf:insert nodeset="instance('log')/event" at="last()" position="after" />
<xf:setvalue ref="instance('log')/event[last()]" value="'Tab One deselected'" />
</xf:action>
Note that the message must be inside a pair of single quotes inside of double quotes.
At the end of the form you can display the data from the log instance by enclosing the output within a repeat.
<div id="event-log">
<xf:repeat nodeset="instance('log')/event" class="log">
<xf:output ref="." />
</xf:repeat>
</div>
You can also style the event log with the following
#event-log {
color: DarkGray;
background-color: Lavender;
}