Customize a form template by using a script

If you are familiar with writing script, you can add a script to your Microsoft Office InfoPath form template by using the Microsoft JScript or the Microsoft Visual Basic Scripting Edition (VBScript) scripting language. Adding script enables you to customize your form template beyond what is available with rules, formulas, data validation, or conditional formatting. For example, you can add a script that creates and sends an e-mail message when a user switches the view in a form based on your form template. You can configure a form template to create and send an e-mail message only by using a script.

In this article

Overview

Compatibility considerations

Set the scripting language for a form template

Display a message each time an event occurs

Add a script that runs when a user saves the form data

Add a script that runs when a user submits the form data

Add a script that runs when a user clicks a button

Add a script that runs when existing forms are merged

Add a script to update the existing forms

Add a script for other events

Overview

You can customize your InfoPath form template by using rules, formulas, data validation, and conditional formatting. Although these features are very flexible and can handle a wide variety of tasks, some tasks are beyond the capabilities of these features. For example, you cannot use rules to send an e-mail message when a user enters a value in a text box on a form. If you need to customize your form template in a way that is beyond the capabilities of these features and you are familiar with writing scripts by using the JScript or VBScript scripting language, you can add a script that runs when a user opens a new form or modifies an existing form that is based on your form template.

When you add a script to a form template, InfoPath starts the Microsoft Script Editor (MSE), which allows you to add, edit, and debug script in a form template and places the cursor in your chosen event. InfoPath automatically adds an event handler to the script. An event handler is the function code in an InfoPath form template that responds to a user action or a change to the XML data in a form. For example, if you want your users to save their forms to several network locations, you can add a script to the OnSaveRequest event handler. When you add a script to run when the user saves a form based on your form template, InfoPath starts the script editor and adds one of the following codes to the script.

Note: The code that InfoPath adds depends on your chosen script language.

JScript

//=======
// 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::OnSaveRequest(eventObj)
{
   // Write the code to be run before saving here.
   eventObj.IsCancelled = eventObj.PerformSaveOperation();
   // Write the code to be run after saving here.
   eventObj.ReturnStatus = true;
}

VBScript

'=======
' 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.
'=======
Sub XDocument_OnSaveRequest(eventObj)
' Write the code to be run before saving here.
eventObj.IsCancelled = eventObj.PerformSaveOperation
' Write the code to be run after saving here.
eventObj.ReturnStatus = True
End Sub

You can then add code in the appropriate places in the event handler that saves the form to the different network location. When a user saves a form based on this form template, InfoPath runs the code in the OnSaveRequest event handler.

Note: This article provides a high-level view of creating scripts in a form template. To learn more about the Microsoft Script Editor and specific objects, methods, events, and properties used in InfoPath, see the InfoPath Developer's reference.

InfoPath automatically adds event handlers for all but one of the following events.

Event handler	Description	Steps for creating
OnAfterChange	This event runs after a user changes the value in the specified control bound to a field. For example, you can display a custom HTML task pane after a user selects an item in a list box control. This event runs after the OnValidate event.	Right-click a control on the form template or a field in the Data Source task pane, point to Programming on the shortcut menu, and then click On After Change Event.
OnAfterImport	This event runs after the user successfully merges several forms into one form.	Manually add the OnAfterImport event handler declaration directly to the script file by using MSE. This event handler cannot be created in design mode.
OnBeforeChange	This event runs after a user changes the value in a control and before the value is added to the specified field bound to that control. For example, you can prevent a user from adding an additional row before filling out the last row in a repeating table.	Right-click a control on the form template or a field in the Data Source task pane, point to Programming on the shortcut menu, and then click On Before Change Event.
OnClick	This event runs when a user clicks a button associated with this event. This event is available after you add a button to the form template. For example, you can perform a complex calculation by using the values in fields in the main data source when a user clicks the button.	Double-click the button control and then on the General tab of the Button Properties dialog box, click Edit Form Code.
OnContextChange	This event runs when the focus changes in the form. For example, this event runs when a user navigates from a text box to a date picker, or when a user switches views. This event occurs after all other events have occurred.	On the Tools menu, point to Programming, and then click On Context Change Event.
OnLoad	This event runs whenever a user creates a new form or opens an existing form based on your form template. For example, you can copy a list of items from a secondary data source to the main data source when a user opens the form.	On the Tools menu, point to Programming, and then click On Load Event.
OnMergeRequest	This event runs when forms based on your form template are merged. For example, you can display the number of forms that were merged to give a user a status during the merge operation.	On the Tools menu, click Form Options. In the Category list, click Advanced. Under Merge forms, select the Merge using custom code check box, and then click Edit.
OnSaveRequest	This event runs when a user saves a form based on your form template. For example, you can save the form based on this form template to more than one location when a user saves the form. InfoPath adds two additional lines of code to this event: a line that saves the form and another line that tells you if InfoPath successfully saved the form.	On the Tools menu, click Form Options. In the Category list, click Open and Save. Under Save behavior, select the Save using custom code check box, and then click Edit.
OnSign	This event runs when a user applies a digital signature to a form. For example, you can add additional data to the digital signature of an expense report form when a user signs it.	On the Tools menu, point to Programming, and then click On Sign Event.
OnSubmitRequest	This event runs when a user submits his or her form data. For example, you can submit the form data to a secure Web service when the user clicks Submit on the File menu. Since InfoPath does not support a data connection to a secure Web service, you need to add a custom data connection that works with your secure Web service.	On the Tools menu, click Submit Options. Select the Allow users to submit this form check box, click Perform custom action using Code, and then click Edit Code.
OnSwitchView	This event runs when a user opens a form based on your form template or switches to another view in the form. For example, when a user switches to a specific view, you can create an e-mail message that contains data from the fields in the form's main data source.	On the Tools menu, click Programming, and then click On Switch View Event.
OnValidate	This event runs when a user changes the value in a control bound to a field. For example, when the user changes the value in a specific control, you can calculate a new value for another control by using the number that the user entered and a number that is in the script. This event occurs after the OnBeforeChange event handler runs.	Right-click a control on the form template or a field in the Data Source task pane, point to Programming on the shortcut menu, and then click On After Validate Event.
OnVersionUpgrade	This event runs when a user opens an existing form and the version number of the form template used by the existing form is older than the version number of the form template in the publish location. When a user opens an existing form, InfoPath checks the version number of the form template associated with the existing form. If the form template has a newer version number, InfoPath runs the OnVersion event handler when the user opens the existing form. For example, imagine that you add a new field to an existing form template and republish it, and you want the new field to be added to the main data source if a user opens an existing form. This event adds the new field to the main data source when a user opens an existing form.	On the Tools menu, click Form Options. In the Category list, click Versioning. In the On version upgrade list, click Use custom event, and then click Edit.

Top of Page

Compatibility considerations

You cannot add script to a browser-compatible form template. You can add script only to a form template whose forms will be filled out in InfoPath. You can customize a browser-compatible form template only by using managed code.

Top of Page

Set the scripting language for a form template

To customize a form template by using script, you can use either Microsoft JScript or Microsoft Visual Basic Scripting Edition (VBScript). By default, InfoPath is configured to add script by using JScript. If your form template does not contain any script or managed code, and you prefer to use VBScript as your scripting language, you can change the scripting language for your form template to VBScript. You cannot use both scripting languages in the same form template.

If the form template already contains script in one language and you want to use the other language, you need to save the existing script so that you can convert the script to the other language, remove the script from the form template through the Form Options dialog box, and then add the converted script back to the form template. InfoPath cannot convert scripts to a new scripting language. Changing the script language in the Form Options dialog box only affects this form template. Other form templates will have JScript as the default scripting language.

1. On the Tools menu, click Form Options.

2. In the Category list, in the Form Options dialog box, click Programming.

3. In the Form template code language list, under Programming language, click VBScript.

   Notes: 

   • After you set the scripting language and create one or more event handlers for a form template, you cannot change the scripting language for the form template.

   • If you have installed Microsoft Visual Studio 2005 Tools for Applications, the default language is Microsoft Visual Basic .NET. You can still use this procedure to change the scripting language to VBScript.

Top of Page

Display a message each time an event occurs

If you want to know what event handlers run in response to an action or other event, you can add temporary code to display a message box whenever the event handler runs. You should use this code only to determine when an event handler runs. After you add this code, you can use preview to view a form based on this form template or to publish the form template and then create a new form template. Some event handlers run only if you create a form after you publish the form template. You can then perform an action that you think might run the event handler. When the event handler runs, you see a message box.

After you determine what actions or events run the event handler, remove the code and then resume designing the form template. If you do not remove this code and then you publish the form template, your users will see this message box when the event handler runs.

1. Add your event handler.

2. To add code in JScript, type XDocument.UI.Alert("The Event name event just ran"); Replace with the name of your event handler. For example, if you add this code to the OnValidate event handler, you would type XDocument.UI.Alert("The OnValidate event handler just ran");

3. To add code in VBScript, type XDocument.UI.Alert("The Event name event just ran") For example, if you add this code to the OnSaveRequest event handler, you would type XDocument.UI.Alert("The OnSaveRequest event handler just ran")

4. To test the code, click Preview on the File menu, or press CTRL+SHIFT+B, and then perform a user action that can start the event. When the event with the line of code occurs, a message box should display your message.

   Note: Some events may require you to publish the form template and then create a form based on this form template before you can perform a user action to start the event.

5. Before you publish the form template and enable your users to fill out forms based on this form template, delete the code that you used to display the message box.

Top of Page

Add a script that runs when a user saves the form data

1. On the Tools menu, click Form Options.

2. In the Category list, in the Form Options dialog box, click Open and Save.

3. Under Save behavior, select the Save using custom code check box, and then click Edit. The Microsoft Script Editor starts with the cursor at the OnSaveRequest event handler.

   JScript

   //=======
   // 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::OnSaveRequest(eventObj)
   {
      // Write the code to be run before saving here.
      eventObj.IsCancelled = eventObj.PerformSaveOperation();
      // Write the code to be run after saving here.
      eventObj.ReturnStatus = true;
   }
   

   VBScript

   '=======
   ' 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.
   '=======
   Sub XDocument_OnSaveRequest(eventObj)
   ' Write the code to be run before saving here.
   eventObj.IsCancelled = eventObj.PerformSaveOperation
   ' Write the code to be run after saving here.
   eventObj.ReturnStatus = True
   End Sub
   

4. Do one or both of the following:

   • To add a script that runs before InfoPath saves the form, replace the comment Write the code to be run before saving here.with your code.

   • To add a script that runs after InfoPath saves the form, replace the comment Write the code to be run after saving here. with your code.

5. To test your changes, click Preview on the Standard toolbar, or press CTRL+SHIFT+B.

   Note: If the event handler runs only after you create a form based on your form template, publish the form template by clicking Publish on the File menu, and then complete the Publishing Wizard. After you publish the form template, create a form and then perform an action to run the event handler.

Top of Page

Add a script that runs when a user submits the form data

1. On the Tools menu, click Submit Options.

2. In the Submit Options dialog box, select the Allow users to submit this form check box.

3. Click Perform custom action using Code, and then click Edit Code. The Microsoft Script Editor starts with the cursor at the OnSubmitRequest event handler.

   JScript

   //=======
   // 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::OnSubmitRequest(eventObj)
   {
      // If the submit operation is successful, set
      // eventObj.ReturnStatus = true;
      // Write your code here
   }
   

   VBScript

   '=======
   ' 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.
   '=======
   Sub XDocument_OnSubmitRequest(eventObj)
   ' If the submit operation is successful, set
   ' eventObj.ReturnStatus = True
   ' Write your code here
   End Sub
   

4. Replace the comment If the submit operation is successful, set eventObj.ReturnStatus = true Write your code here with your code.

5. To test your changes, click Preview on the Standard toolbar, or press CTRL+SHIFT+B.

Top of Page

Add a script that runs when a user clicks a button

1. Add a new button to a view in the form template, and then double-click the button.

   Note: If you are adding script to an existing button, double-click the existing button instead.

2. Click the General tab.

3. Click Edit Form Code. The Microsoft Script Editor starts with the cursor at the OnClick event handler for that button.

   JScript

   //=======
   // 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 Button Name::OnClick(eventObj)
   {
   // Write your code here
   }
   

   VBScript

   '=======
   ' 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.
   '=======
   Sub Button Name_OnClick(eventObj)
   ' Write your code here
   End Sub
   

4. Replace the comment Write your code here with your code.

5. To test your changes, click Preview on the Standard toolbar, or press CTRL+SHIFT+B.

Top of Page

Add a script that runs when existing forms are merged

1. On the Tools menu, click Form Options.

2. In the Category list, in the Form Options dialog box, click Advanced.

3. Under Merge forms, select the Enable form merging check box.

4. Select the Merge using custom code check box, and then click Edit. The Microsoft Script Editor starts with the cursor at the OnMergeRequest event handler.

   JScript

   //=======
   // 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::OnMergeRequest(eventObj)
   {
   // Write the code that handles each form being merged here.
   XDocument.ImportDOM(eventObj.DOM);
   eventObj.ReturnStatus = true;
   }
   

   VBScript

   '=======
   ' 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.
   '=======
   Sub XDocument_OnMergeRequest(eventObj)
   ' Write the code that handles each form being merged here.
   XDocument.ImportDOM(eventObj.DOM)
   eventObj.ReturnStatus = True
   End Sub
   

5. Replace the comment Write the code that handles each form being merged here. with your code.

6. To test the code in this event, publish the form template, create several forms based on this form template, and then merge the form templates.

   Note: Find links to more information about publishing your form template in the See Also section.

Top of Page

Add a script to update the existing forms

If you updated a previously published form template, and you want to update the existing forms based on that form template, you can add script to the updated form template that runs when a user opens one of the existing forms. When a user opens an existing form, InfoPath checks the version number of its associated form template at the publish location. If the version number of the form template at the publish location is newer than the version number in the existing form, indicating that it has been updated, InfoPath runs the code in this event to update the existing form.

1. On the Tools menu, click Form Options.

2. In the Category list, in the Form Options dialog box, click Versioning.

3. In the On version upgrade list, click Use custom event, and then click Edit. The Microsoft Script Editor starts with the cursor at the OnVersionUpgrade event handler.

   JScript

   //=======
   // 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::OnVersionUpgrade(eventObj)
   {
   // Write your code here
   }
   

   VBScript

   '=======
   ' 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.
   '=======
   Sub XDocument_OnVersionUpgrade(eventObj)
   ' Write your code here
   End Sub
   

4. Replace the comment Write your code here with your code.

5. To test the code in this event, publish the form template, create several forms based on this form template, modify and publish an updated version of the form template, and then open an existing form based on the older version of this form template.

   Note: Find links to more information about publishing your form template in the See Also section.

Top of Page

Add a script for other events

This procedure can be used to add the following event handlers to your form template:

• OnAfterChange

• OnBeforeChange

• OnContextChange

• OnLoad

• OnSwitchView

• OnSign

• OnValidate

• On the Tools menu, point to Programming, and then click the event to add to the event handler. The Microsoft Script Editor starts with the cursor at the event handler that you selected.

• Replace the comment Write your code here with your code.

Top of Page