Professional XML (Programmer to Programmer)
A form populated based on some XML and XPath expressions is useful for displaying data, but a form frequently has to perform some processing as well. Therefore, you must add logic or code to react to changes made by the user. XForms provides this capability through events and actions. Events are associated with form elements to react to data updates, navigation, errors or other stages in the creation and editing of the form. Actions are elements that are invoked based on these events.
Events
Events are at the core of XForms development. They are raised at significant parts of the form's lifetime and cause either the implementation or added code to execute when the event occurs. XForms uses the XML Events module (w3.org/2001/xml-events) for defining these events. The event can be caught by any element, although they are frequently associated with trigger controls and actions (see the following). XForms events fall into four broad categories:
-
q Initialization-These events are important in the creation and rendering of the form by the implementation. They include the xforms-model-construct event, that is passed to each control, causing them to render themselves onto the form, and the xforms-ready that is fired when the form is complete and ready for editing. These events are not usually used by the developer, although xforms-ready can be used to notify the user that the form is ready for his input.
-
q Interaction-These events are thrown as the user navigates through the form and changes values. Some examples of these events are the xforms-submit (occurs when the form is submitted), xforms-recalculate (occurs when any value is changed), and xforms-focus (occurs as a control receives focus).
-
q Notification-These events occur when controls are used, such as when a button is clicked or text is entered in a field. They include the most commonly used event, DOMActivate (the default event for a control, such as a button click) as well as xforms-value-changed, xforms-insert, and the xforms-valid/xforms-invalid events.
-
q Error indication-These events are thrown when major errors occur in the processing of a form. They include xforms-compute-exception, which occurs when a major calculation error occurs (such as division by zero). You should handle these events to avoid the default processing, which frequently causes the form to be closed.
You process events by associating them with a control or element such as action. When the event occurs, the action is executed.
Actions
Actions are behaviors that you want invoked at points in the lifespan of a form. For example, actions can be used to insert data, change values in fields, or recalculate the form. Typically, actions are performed using trigger elements, but this is not always the case; they can be associated with any form control. The following table discusses the commonly used actions available to XForms developers.
| Action | Description |
|---|---|
| action | Enables the developer to combine multiple actions into a set. Each of the child elements of this action are performed in sequence, so you could add a new row to a repeat element and set the value of each of the fields. |
| dispatch | Invokes the desired event. This provides the means of forcing a particular event to occur, such as an error message (using xforms-help). Many of the following actions can also be carried out through dispatch. |
| recalculate | Recalculates the form. Although this is typically done when the fields change, the recalculate action can force this behavior. |
| revalidate | Runs all data validation on the form. Although this is typically done as the fields change, the revalidate action can force this behavior. |
| Refresh | Forces the data back to the original instance data, removing changes. |
| setfocus | Sets the focus to a particular control. The control is identified using an id attribute. <xf:trigger> <xf:label>Setfocus</xf:label> <xf:action ev:event="DOMActivate"> <xf:setfocus control="B" /> </xf:action> </xf:trigger> |
| setvalue | Assigns a value to a field in the model. The field is identified using an XPath expression. <xf:trigger> <xf:label>Set A to 20</xf:label> <xf:action ev:event="DOMActivate"> <xf:setvalue ref="@a">20</xf:setvalue> </xf:action> </xf:trigger> |
| Send | Submits the form. This is equivalent to using a submit element, and requires the id of the submit element. |
| Insert | Adds a new row to a repeat element. This creates the new fields required for the node. Data from the last member of the existing collection is used to fill these fields. The developer is responsible for identifying the location of the newly added row using the two attributes position (either “before” or “after”) and at (the index). <xf:trigger> <xf:label>Add</xf:label> <xf:action ev:event="DOMActivate"> <xf:insert nodeset="ex:employee" position="after" at="count(//ex:employee)" /> </xf:action> </xf:trigger> |
| Delete | Deletes a row from a repeat element. The index must be provided. <xf:trigger> <xf:label>Delete</xf:label> <xf:delete ev:event="DOMActivate" nodeset="ex:employee" at="index('empitem')" /> </xf:trigger> |
| setindex | Selects a row in a repeat element. Many implementations highlight the selected row for clarity. |