Show All

# Form events in the Events developer sample form

The Events developer sample form implements a variety of Microsoft Office InfoPath 2003 form events that can be used to respond to specific activities that occur when a form is opened and while it is being filled out. Form events can occur when a form's version number is validated, when a form is opened, when a form view is changed, and after a form has been merged with another form.

The following table lists each of the form events implemented in the Events developer sample form, along with a description of how they are used.

Event | Description
--- | ---
OnVersionUpgrade | Used to verify that the version number of the form being opened matches the version number of the form when it was originally designed. If the version numbers do not match, this event occurs and scripting code can be used to update the form or display an error message.
OnLoad | Used to initialize the form as it is being opened. When this event occurs, scripting code can be used to set the appropriate view based on data contained in the form.
OnSwitchView | Used when changing from one view to another. This event occurs when a user changes views, and scripting code can be used to insert data into the form.
OnAfterImport | Used to provide additional processing after a form has been merged with another form. This event occurs after data is imported from another form, and scripting code can be used to set the appropriate view based on the merged data contained in the form.

Note The OnSubmitRequest event is also a form event, but it was not used in the Events developer sample form.

Using the OnVersionUpgrade event

The OnVersionUpgrade event occurs when a form is opened that contains a version number that is older than the version number of the form when it was originally designed. The version number of a form is contained in the solutionVersion attribute of the form's mso-infoPathSolution processing instruction.

To use the OnVersionUpgrade event, you use the Advanced tab of the Forms Options dialog box, which is available on the Tools menu in design mode. This tab allows you to set the version number of the form and specify how you want InfoPath to handle version upgrades. To enable the OnVersionUpgrade event, select Use script event in the On version upgrade box, and then click Edit. This opens Microsoft Script Editor (MSE) and displays the InfoPath-generated event handler.

Note Event handlers in InfoPath must be created in design mode.

In the Events developer sample form, the OnVersionUpgrade event is determines whether the form with the incorrect version number contains an EmailAddress element. If it does not, one is added. If the operation is not successful, the Alert method of the UI object is used to notify the user. The following example from the Events developer sample form shows the OnVersionUpgrade event handler:

    function XDocument::OnVersionUpgrade(eventObj)
    {
       if (!XDocument.DOM.selectSingleNode("/Customers/CustomerInfo/EmailAddress"))
       {
          try
          {
             // Create the new element.
             var objItemNode =
                XDocument.DOM.selectSingleNode("/Customers/CustomerInfo")
                   .ownerDocument.createElement("EmailAddress");

             // Add the new <item> element to the XML document as a
             // child of the <order> element.
             XDocument.DOM.selectSingleNode("/Customers/CustomerInfo")
                .appendChild(objItemNode);
          }
          catch(ex)
          {
             XDocument.UI.Alert("There was an error inserting the " +
               "<EmailAddress> node.\nDescription: " + ex.description);
          }
       }
    }

To test the OnVersionUpgrade event, open the Events developer sample form, click Open on the File menu, and open the WRONGVER.XML file located in the SAMPLES folder. This form contains a version number that is older than the original Events developer sample form, and it does not contain an EmailAddress element. When you save the form after InfoPath has corrected it using the scripting code contained in the OnVersionUpgrade event, the version number and EmailAddress element are updated.

Using the OnLoad event

The OnLoad event occurs when an InfoPath form is opened (or loaded).

To use the OnLoad event, you click On Load Event on the Script submenu located on the Tools menu in design mode. This opens Microsoft Script Editor (MSE) and displays the InfoPath-generated event handler.

Note Event handlers in InfoPath must be created in design mode.

In the Events developer sample form, the OnLoad event checks the form's underlying XML document for the existence of certain data. Based on the values that are found, the OnLoad event then sets the appropriate view using the IsDefault property of the ViewInfos collection, which is accessed through the XDocument object. The following example from the Events developer sample form shows the OnLoad event handler:

    function XDocument::OnLoad(eventObj)
    {
       oContactedNode = XDocument.DOM
          .selectSingleNode("/Customers/CustomerInfo/Contacted");
       oArchivedNode = XDocument.DOM
          .selectSingleNode("/Customers/CustomerInfo/Archived");
       oCustomerName = XDocument.DOM
          .selectSingleNode("/Customers/CustomerInfo/CustomerName");

       if (oContactedNode.text == "false" && !oCustomerName.text)
          XDocument.ViewInfos("New Customer").IsDefault = true;
       else if (oContactedNode.text == "false" && oCustomerName.text)
          XDocument.ViewInfos("Contact Customer").IsDefault = true;
       else
          XDocument.ViewInfos("Archive Customer").IsDefault = true;
    }

Using the OnSwitchView event

The OnSwitchView event occurs when a user changes views in an InfoPath form.

To use the OnSwitchView event, you click On Switch Views Event on the Script submenu located on the Tools menu in design mode. This opens Microsoft Script Editor (MSE) and displays the InfoPath-generated event handler.

Note Event handlers in InfoPath must be created in design mode.

In the Events developer sample form, the OnSwitchView event adds a note to the Archived Customer Notes field each time the Archived Customer view is selected. This is accomplished by using the selectSingleNode method of the XML DOM, which is accessed through the DOM property of the XDocument object. The following example from the Events developer sample form shows the OnSwitchView event handler:

    function XDocument::OnSwitchView(eventObj)
    {

       var oDate = new Date();

       if (XDocument.View.Name == "Archive Customer")
       {
          var oNotesNode = XDocument.DOM
             .selectSingleNode("/Customers/CustomerInfo/Notes");
          var oDivNode = XDocument.DOM
             .createNode(1, "div", "http://www.w3.org/1999/xhtml");

          oDivNode.text = "Note recorded " + oDate.toString();
          oNotesNode.appendChild(oDivNode);
       }
    }

Using the OnAfterImport event

The OnAfterImport event occurs after a form has been merged with (or imported into) another form.

In the Events developer sample form, the OnAfterImport event sets the appropriate view based on the data that the form contains after the merge is complete. This is accomplished by using the SwitchView method of the View object that is accessed through the XDocument object. The following example from the Events developer sample form shows the OnAfterImport event handler:

    function XDocument::OnAfterImport(eventObj)
    {
       XDocument.View.SwitchView("Archive Customer");
    }

Note The OnAfterImport event is not available in design mode. To use this event, you must manually create the event handler in the scripting file as shown in the preceding example.

To test the OnAfterImport event, open the Events developer sample form, click Merge Forms on the File menu, and open the CUSTOMER.XML file located in the SAMPLES folder. This form contains customer contact information that can be merged with the Events developer sample form.

©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