Validation Events

InfoPath's validation events are, not surprisingly, intended to be used in the validation of InfoPath form data. There are three validation events: OnBeforeChange , OnValidate , and OnAfterChange , which occur in that order.

Validation of InfoPath form data is described in Chapter 10, "Validating Form Data," p. 179 .

The DataDOMEvent object is passed as an argument to each of the three InfoPath validation events.

To learn more about the methods and properties of the DataDOMEvent object, see "The DataDOMEvent Object," p. 314 (Chapter 18).

The OnBeforeChange Event

The OnBeforeChange event is the first of the three validation events to occur when the user makes a change in the values visible in a form control. The OnBeforeChange event fires when the user tabs to another form control or clicks anywhere outside the form control that has been edited. During the OnBeforeChange event, the XML DOM is read-only.

An event handler for OnBeforeChange can be used to check whether a desired condition is met. If the desired condition is not met, the value of the ReturnStatus property of the DataDOMEvent object is set to false . In that case, no change can be made to the XML DOM and an error message is displayed to the user.

The OnBeforeChange.xsn sample form template has script that won't allow the second text box to be filled in before the first. The code for the OnBeforeChange event handler is shown here:

 function msoxd_my_DoSecond::OnBeforeChange(eventObj) {  var FirstNode = XDocument.DOM.selectSingleNode("my:myFields/my:DoFirst"); if (!FirstNode.text) {  eventObj.ReturnMessage = "You must fill in the Do First text box before filling in this one.";  eventObj.ReturnStatus = false ;  return; } // end if  // if the test wasn't satisfied then FirstNode contains some data  eventObj.ReturnStatus = true;  return; } 

The DoFirst node is assigned to the FirstNode variable. Then the existence of text in the text property of FirstNode is tested using the if statement. If there is no text associated, we know that the first text box has not been filled in first as it should have been. A string is assigned to the ReturnMessage property of the DataDOMEvent object, and the ReturnStatus property is set to false . Then the function returns.

This causes an error message to be displayed containing the string, which is the value of the ReturnMessage property (see Figure 19.1).

Figure 19.1. The value of the ReturnMessage property is displayed.

When you click OK in the error message dialog, notice that the text in the second text box is erased, indicating that the XML DOM node corresponding to the second text box has not been changed.

The OnValidate Event

The OnValidate event occurs after the OnBeforeChange event completes and before the OnAfterChange event. During the OnValidate event, the XML DOM is in read-only mode. Script code in an event handler for the OnValidate event can check whether the data is valid.

After the OnValidate event has completed successfully, the XML DOM is returned to read-write mode and the appropriate change is made to the relevant node in the XML DOM.

The OnAfterChange Event

The OnAfterChange event occurs following the OnValidate event and after any change has been made to the XML DOM node associated with a form control. The OnAfterChange event may be used to calculate a total or some other numeric value derived from a newly entered (and changed) value in the data source.

The OnAfterChange.xsn sample form template uses the OnAfterChange event to calculate a total and display it in a message box. The function is shown here:

 function msoxd_my_field1::OnAfterChange(eventObj) {  if (eventObj.IsUndoRedo) { // An undo or redo operation has occurred and the DOM is read-only.  return; } // Declare variables var Total; var numbers, number; Total = 0; // Initialize Total variable numbers = XDocument.DOM.selectNodes("/my:myFields/my:group1/my:group2/my:field1"); numbers.reset();  number = null; // Initialize number variable  while ((number = numbers.nextNode()) != null) {  Total += Number(number.text); // Use the Number() function to cast text to numeric  } // end while  XDocument.UI.Alert("The total is now: " + Total); // Display the total } 

The Total variable is initialized to . The selectNodes() method is used to select all the my:field1 nodes in the document. The numbers.reset() method navigates back to the beginning of the nodes. The test for the while loop is whether there is another node in numbers . If there is another node, the text value of that node is cast to a numeric value using the Number() function and then added to the current value of the Total variable.

Once there is no longer another node, the while loop exits and the value of the Total variable is displayed using the Alert() method of the UI object.

There is also an expression box that uses XPath to perform the same calculation. Notice that the value in the expression box is only updated after the event handler for the OnAfterChange event has completed.

SHOP TALK
VALIDATION IS AUTOMATIC AND CONSISTENT

InfoPath events and scripting code allow the developer to produce interactive forms that have rich functionality. Much of the scripting code you might have written for HTML/XHTML forms is unnecessary in InfoPath forms, because data validation is an important focus in HTML forms. In InfoPath, you can perform most of the necessary validation using W3C XML Schema and rules created using the InfoPath user interface. You can, of course, add scripting code if necessary.

Events such as OnAfterChange can be used to fill a secondary data source with the information appropriate to the component of the data source that has changed. By including appropriate script in the handler for the OnAfterChange event, you can retrieve the relevant data.