Last modified on 27 November 2013, at 13:43

XForms/Events Overview

MotivationEdit

You want to be able to perform various tasks at various part of the form execution.

MethodEdit

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 TypesEdit

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.

XForms events
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 FileEdit

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;
}