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
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:
- Open the Data Validation developer sample form in design mode.
- If you do not see the Data Source task pane, click Data Source on the View menu.
- 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.
- Click the Validation and Script tab.
- 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. |
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.