Responding to form events
You can write scripting code to respond to various events that can occur in Microsoft Office InfoPath 2003 as a user fills out a form. In InfoPath, events take the form of event handlers that are created when working with a form in design mode.
InfoPath event handlers must be initially created in design mode because, in addition to the scripting declarations that are created in a form's primary scripting file, entries are also made in the form definition (.xsf) file. After you have created an event handler, you should not alter its declaration in the primary scripting file.
For information about creating the InfoPath event handlers, see About the programming environment.
Overview of the event objects
The InfoPath object model implements nine event objects; the event object you use is determined by the event handler you use. The following table lists each of the InfoPath event objects, the event handlers they are associated with, and a description of the functionality they provide.
| Name | Event handlers | Description |
|---|---|---|
| DataDOMEvent object | OnBeforeChange, OnValidate, OnAfterChange | Returns a reference to a form's underlying XML document, the return status, and other properties that contain information about the XML node during an XML Document Object Model (DOM) change. Also includes a method for raising an error. |
| DocActionEvent object | OnClick | Returns a reference to a form's underlying XML document, the return status, and the source XML node during a button click in the form area. |
| DocContextChangeEvent object | OnContextChange | Returns information about the XML Document Object Model (DOM) node that is the current context of the form's underlying XML document. |
| DocEvent object | OnSwitchView, OnAfterImport | Returns a reference to a form's underlying XML document during a switch view or form merge operation. |
| DocReturnEvent object | OnLoad, OnSubmitRequest | Returns a reference to a form's underlying XML document and the return status during the loading or submission of a form. |
| MergeEvent object | OnMergeRequest | Returns properties and methods that can be used during an OnMergeRequest event to programmatically interact with a form's underlying XML document and to determine merge properties such as the number of files being merged. |
| SaveEvent object | OnSaveRequest | Returns a number of properties and methods that can be used during a save operation from the OnSaveRequest event handler to programmatically interact with a form's underlying XML document, determine save properties, and perform the save operation. |
| SignEvent object | OnSign | Used to add additional data to the digital signature. |
| VersionUpgradeEvent object | OnVersionUpgrade | Returns a reference to a form's underlying XML document, the return status, and the document and solution version numbers during the version upgrade operation. |
Using the event objects
As mentioned previously, when you create an event handler, InfoPath creates the event handler's declaration in the form's primary scripting file. In the declaration of the event handler, InfoPath uses eventObj as the name of the parameter that is passed to the event handler. This parameter contains the event object that is associated with the event handler. For example, when you create the OnLoad event in design mode, InfoPath creates the OnLoad event handler in the scripting file, and then opens the Microsoft Script Editor (MSE) so that you can add your scripting code to the following event handler declaration:
//=======
// The following function handler is created by Microsoft Office InfoPath.
// Do not modify the name of the function or the name and number of arguments.
//=======
function XDocument::OnLoad(eventObj)
{
// Write your code here.
}
When writing scripting code for an event handler, you can use the properties and methods implemented by the event object that is passed through the eventObj parameter. For example, in the following OnBeforeChange event handler, the NewValue property of the DataDOMEvent event object is used to check the value of the field that was just changed. If it is blank, the ReturnMessage property of the DataDOMEvent event object is used to display an error to the user in a dialog box, and the ReturnStatus property is set to false, indicating that the changes the user made should not be accepted.
function msoxd__myField_attr::OnBeforeChange(eventObj)
{
// Determine whether there is a new value.
if (eventObj.NewValue == "")
{
// The value is blank, so display an error message and roll back the changes.
eventObj.ReturnMessage = "You must supply a value for this field.";
eventObj.ReturnStatus = false;
return;
}
}
Note Each of the InfoPath event objects implements different properties and methods. For more information about a particular event object, click the appropriate object in the preceding table.