Show All

# Script-based validation in the Data Validation developer sample form

Script-based validation is specified in the business logic script file associated with a Microsoft Office InfoPath 2003 form, and it provides more flexibility than custom validation or schema-based validation. Using script-based validation, you can specify when a field should be validated (for example, when the user first types data into a field, after the user leaves a field, or after data is validated by the schema). You can also write script that runs when a form is opened or when the user switches views. The script you write can perform a variety of functions, including comparing fields, calculating values, showing error messages, updating values, and revising other fields.

Note InfoPath supports writing script in Microsoft VBScript and Microsoft JScript. However, you cannot mix the scripting languages used within a single form.

To create script-based data validation, you use InfoPath design mode to create an event handler (also called an event function), and then you write scripting code for the event handler using the Microsoft Script Editor (MSE). For each event handler that you create, InfoPath places an entry in the form definition (.xsf) file that contains the name of the event handler and the XML Document Object Model (DOM) node that the event handler is associated with.

Because the event handler is referenced in the .xsf file, you cannot create a new event handler entirely from within MSE— you must initially create the event handler in InfoPath design mode. Since InfoPath is used to create the declaration of the event handler, you cannot modify the event handler name or its arguments once it has been created.

Event handlers in the form definition file

In the Data Validation developer sample form, InfoPath created a domEventHandler element within the domEventHandlers section of the .xsf file for each event handler. The following is an example of the event handlers created in the .xsf file of the Data Validation developer sample form:

    <xsf:domEventHandlers>
       <xsf:domEventHandler handlerObject="msoxd__itemB_quantityListB"
          match="/sampleData/listB/itemB/quantityListB">
       </xsf:domEventHandler>
       <xsf:domEventHandler handlerObject="msoxd__shippingDates"
          match="/sampleData/shippingDates">
       </xsf:domEventHandler>
       <xsf:domEventHandler handlerObject="msoxd__total"
          match="/sampleData/listB/total">
       </xsf:domEventHandler>
       <xsf:domEventHandler handlerObject="msoxd__creditLimit"
          match="/sampleData/creditCardInfo/creditLimit">
       </xsf:domEventHandler>
       <xsf:domEventHandler handlerObject="msoxd__creditCardInfo"
          match="/sampleData/creditCardInfo">
       </xsf:domEventHandler>
    </xsf:domEventHandlers>

As shown in this example, for every event handler created in InfoPath design mode, a domEventHandler element was created in the .xsf file; each of these elements contains a handlerObject attribute that specifies the name of the event handler and a match attribute that specifies the XML DOM node that the event handler is associated with.

Viewing event handlers in the form definition file

To view the event handlers that were used to implement the script-based validation constraints in the Data Validation developer sample form, do the following:

1. Open the Data Validation developer sample form in design mode.
2. If you do not see the Data Source task pane, click Data Source on the View menu.
3. In the Data Source task pane, right-click the field whose validation you want to view or modify, and then click the Properties menu item to open the Field or Group Properties dialog box.
4. Click the Validation and Script tab.
5. In the Events box, select the event that you wish to edit, and then click Edit to open MSE. The script code for the selected event appears in the code editor window.

Note While it is necessary to create event handlers in design mode using these steps, once you have created an event handler, you can open MSE from InfoPath by clicking the Tools menu, pointing to Script, and clicking Microsoft Script Editor, or by pressing ALT+SHIFT+F11.

Script-based event handlers and functions

In the Data Validation developer sample form, a number of event handlers and functions are used for script-based validation. The following table lists each of these event handlers and functions and describes how they are used.

Function | Description
--- | ---
`msoxd__shippingDates::OnBeforeChange` | An event handler that is used to validate shipping dates. It returns a True or False value depending on whether the dates are valid according to business rules, and it sets the ReturnMessage and ReturnStatus properties of the DataDOMEvent object to return an error message to the user.
`msoxd__itemB_quantityListB::OnValidate` | An event handler that is used to validate the quantity values within each block. It uses the ReportError method of the DataDOMEvent object to return an error message to the user.
`msoxd__itemB_quantityListB::OnAfterChange` | An event handler that is used to update the Total field based on the number of block quantities entered. This event occurs after the data has been validated in the OnValidate event. It calls the general-purpose GetTotal function to do the calculations.
`msoxd__total::OnValidate` | An event handler that is used to validate the value in the Total field. It uses the ReportError method of the DataDOMEvent object to return an error message to the user.
`msoxd__creditCardInfo::OnValidate` | An event handler that is used to validate the credit card limits for each credit card type. It calls the ValidateCreditInformation general-purpose function to perform the validation.
`msoxd__creditLimit::OnBeforeChange` | An event handler that is used to validate the credit card limit value. It uses the ReturnMessage and ReturnStatus properties of the DataDOMEvent object to return an error message to the user.
`ValidateCreditInformation` | A general-purpose function that is used to validate the credit card limits for each credit card type. It uses the ReportError method of the DataDOMEvent object to return an error message to the user.
`GetTotal` | A general-purpose function that is used to add all of the quantity values. It returns the total value of all the quantities.
`BtnSubmitShipDates::OnClick` | An event handler that is used to simulate the connection to a back-end application that validates the order and shipping dates entered in the form. It uses the Alert method of the UI object to provide information to the user.

Using the DataDOMEvent object

In the Data Validation developer sample form, the DataDOMEvent object is used in the `msoxd__itemB_quantityListB::OnValidate` event handler to validate the number of blocks entered in the Quantity field. It returns an error message to the user if the data does not meet the specified criteria, which in this case is a numerical value that is greater than 50 or less than 0.

The Site property of the DataDOMEvent object is used to return a pointer to the XML DOM node for the Quantity field, and the nodeTypeValue property of the XML DOM is used to access the value of the field. If the value of the field does not match the data validation criteria, then the ReportError method of the DataDOMEvent object is used to return an error message to the user. The following is the JScript code used to implement the `msoxd__itemB_quantityListB::OnValidate` event handler:

    function msoxd__itemB_quantityListB::OnValidate(eventObj)
    {
       if (parseInt(eventObj.Site.nodeTypedValue, 10) > 50)
       eventObj.ReportError(eventObj.Site, "Invalid quantity.  The total number
          of each type of block cannot exceed 50.", false);

       if (parseInt(eventObj.Site.nodeTypedValue, 10) < 0)
       eventObj.ReportError(eventObj.Site, "Invalid quantity.  The total number
          of each type of block cannot be less than 0.", false);
    }

As shown in this example, multiple data validation constraints can be checked against a single field, and you can create a custom error message for as many validation constraints as needed.

©2003-2004 Microsoft Corporation. All rights reserved. Permission to copy, display and distribute this document is available at: http://msdn.microsoft.com/library/en-us/odcXMLRef/html/odcXMLRefLegalNotice.asp