Using a script, you can manipulate both the InfoPath user interface and the abstract XML document underlying the form. You can also call external code to add almost any functionality to a form. This can be useful in a broad range of situations, for example:

Scripts can be executed when the user clicks a button on the form, when the user changes a value, when a form is first loaded, or in response to a number of other events. In this chapter we will provide a number of examples of InfoPath scripts, focusing mostly on the XML aspects rather than user interface customization.

Let’s start with a very simple example to show the basics of script creation. To implement a simple script that displays a message for the user:

Now, test your script by filling out the form you just created. The easiest way to do this is to click Preview Form on the toolbar. When clicking the Button button, you should get a dialog saying “This is your first script”, as shown in Figure 10-3.

Figure 10-3. Output of the simple script

Let’s take a closer look at the script in the example. The name of the function into which you inserted your code is something like CTRL1_5::OnClick.CTRL1_5 is the script ID of the button, and OnClick is the name of the event that causes that function to be executed. We will look more closely at events in section 10.4, “Events”, on page 232.

The single line of code refers to the object XDocument, which represents the current document that is displayed in the form. It then refers to the document’s user interface via the property UI. Finally, it calls the Alert method of that UI object, passing it one parameter that is the string “This is your first script”. The Alert method is used to display a message.

As you may have noticed, the script file that appears in Script Editor contains other functions in addition to the one you are editing at the moment. Each form has at least one script file associated with it that contains all the necessary functions for that form.

InfoPath scripts can be written in JScript or VBScript, the default being JScript. All of the examples in this chapter are written in JScript. These two languages are similar and are often embedded in HTML to enhance Web pages. To change the scripting language for a form, click Options on the Tools menu and click the Design tab. Under Scripting, choose whether you want to write scripts in JScript or VBScript.

Script files can contain a list of functions for that form, as well as variable definitions and comments. Some functions may be associated with a particular field or button, while others are associated with the form as a whole. In addition, you can create a library of added functions in the script file in order to reuse code.

When a form is saved, the script file is stored within the .xsn file. If you use the Extract Form Files command to extract the files associated with the form, the script file will appear as a separate file whose extension is .js. By default, it will be named script.js.

It is possible to create additional script files and associate them with the form using the Resource Manager which is accessible from the Tools menu. This is useful for sharing functions across multiple forms. However, you will not be able to edit the additional script files using Script Editor; you will have to edit them in another tool such as a text editor or Visual Studio.

In our previous example, we associated a script function with a button, so that every time the button was clicked, the script function was executed. There are a number of different kinds of events that trigger script execution in addition to the clicking of a button. They include positioning the cursor on a field, changing a value, loading a form, switching views, and more. The InfoPath events are listed in Table 10-1.

A script function may be associated with a particular event, and in some cases a particular field or button. In the script, the name of the function will indicate the event. For example:

You don’t have to specify these function names yourself. They are generated by XPath when you launch Script Editor and they should not be changed. However, it is useful to understand their meaning when editing the script. Throughout the rest of the chapter, we will see examples of working with these events.

In our previous example, we used Script Editor to create the simple script function. Script Editor is a separate application that is launched from Info-Path when the user needs to create or edit a script function. In our example, we launched it from the Button Properties dialog, and it automatically created an empty function associated with that button.

There are a number of other ways to launch Script Editor, depending on the event that will trigger the function to be executed:

In all these cases, InfoPath creates an empty “stub” function for you, and you just need to fill in the function body. Script Editor can also be launched directly from the Script submenu of the Tools menu.

Microsoft provides an object model for use in InfoPath scripts. The object model allows you to programmatically manipulate the underlying XML document, as well as the user interface itself. Figure 10-5 shows the basic hierarchy of the object model. Only the most commonly used objects are shown.

Figure 10-5. InfoPath object hierarchy

At the top of the object model hierarchy is the Application object which represents the application itself. From Application, you can access the open InfoPath windows via the Windows property, as well as the open XML documents, via the XDocuments property.

In most scripts you will be interested in performing some operation that involves the currently displayed XML document, which can be accessed via the XDocument object. For example, in 10.2, “A simple sample script”, on page 228, we used the method call XDocument.UI.Alert to display a message box within the current document. The XDocument object has a number of properties that are useful in scripts:

In addition, there are event objects that are passed to scripts as parameters when an event, such as clicking a button or changing a value, occurs.

Browsing the object model

The InfoPath object model is fully documented in the InfoPath Developer’s Reference, which is included in the InfoPath help. This document is a reference guide for the various events and objects and their associated properties and methods.

In addition, you can browse the InfoPath object model interactively in Script Editor using Object Browser. If Object Browser is not already displayed, point to Other Windows on the View menu, then click Object Browser.

In Object Browser, you can traverse the object model much as you might in Windows Explorer. When an object is selected in the left-hand pane, its members (functions and properties) are displayed to the right, as shown in Figure 10-6. The pane at the bottom of Object Browser displays further information about the component, often including a description of its purpose.

Figure 10-6. Object Browser

One of the most common uses for scripts is to perform validation, either because custom error messages are desired, or because the validation involves complex business rules. In this section we will look at three different examples of validation scripts. In the process, we will learn more about JScript as well as the InfoPath object model. All of the examples in this chapter can be found in the order_scripts.xsn example file. This form, shown in Figure 10-7, is a slightly modified version of our order form from the previous chapter.

Figure 10-7. Revised Order Form (order_scripts.xsn)

function msoxd__item_number_attr::OnValidate(eventObj)
{
  // Make sure it is less than 1000
  if (eventObj.Site.nodeTypedValue > 999)
    eventObj.ReportError(eventObj.Site,
       "Invalid product number: " +
       eventObj.Site.nodeTypedValue +
       "  The product number must be less than 1000.")
}

function msoxd_ns1_item::OnValidate(eventObj)
{
  // Retrieve the necessary nodes and values
  var itemNode = eventObj.Site
  var quantNode = itemNode.selectSingleNode("ns1:quant")
  var quant = quantNode.nodeTypedValue
  var prodNum = itemNode.selectSingleNode("@number").nodeTypedValue

  //test the condition and report error
  if (prodNum == 999 && quant > 1)
    eventObj.ReportError(quantNode,
     "Quantity cannot exceed 1 for product number 999.", false)
}

function msoxd_ns1_addr2::OnBeforeChange(eventObj)
{
  // Retrieve the necessary nodes and values
  var addr1 = XDocument.DOM.selectSingleNode(
                  "/ns1:order/ns1:shipTo/ns1:addr")
  var addr2 = XDocument.DOM.selectSingleNode(
                  "/ns1:order/ns1:shipTo/ns1:addr2")

  //test the condition and report error
  if (addr1.text == "" && addr2.text != "")
  {
    eventObj.ReturnMessage =
      "A second address line cannot be specified without a first."
    eventObj.ReturnStatus = false
    return
  }
  eventObj.ReturnStatus = true
  return
}

Another common use for scripts in InfoPath is to perform calculations, such as totals, averages, tax amounts, or currency conversions. Calculation scripts are often associated with the OnAfterChange event, which occurs after validation. This is useful for updating fields in response to changes in other fields, for example to update a total when a line item has changed.

Suppose we want each line item in our order form to reflect the total cost of that item, namely the quantity times the price. In addition, we want a summary section that shows the total number of items ordered, and the total cost of the order. We could associate script functions with the quantity and price fields, so that any time either of them change, the totals are updated. The script functions might look like Example 10-5.

function msoxd_ns1_quant::OnAfterChange(eventObj) {
  if (eventObj.IsUndoRedo)
      return;
  updateCost(eventObj.Site.parentNode)
  updateTotals()
}

function msoxd_ns1_price::OnAfterChange(eventObj) {
  if (eventObj.IsUndoRedo)
      return;
  updateCost(eventObj.Site.parentNode)
  updateTotals()
}

This function just calls two other functions, updateCost and updateTotals, that are defined later in the script file. The updateCost function, shown in Example 10-6, calculates the cost of each line item.

function updateCost(thisItemNode)
{
  var thisQuant = thisItemNode.selectSingleNode("ns1:quant")
  var thisPrice = thisItemNode.selectSingleNode("ns1:price")
  var thisCost = thisItemNode.selectSingleNode("ns1:cost")
  var nQuant = parseFloat(thisQuant.nodeTypedValue)
  var nPrice = parseFloat(thisPrice.nodeTypedValue)
  var nCost = nPrice * nQuant;
  thisCost.nodeTypedValue = nCost
}

On lines 3 through 5, it assigns the three relevant nodes to variables. Then, on lines 6 and 7, it extracts the typed value of the quantity and price nodes and converts them to JScript floating point numbers using the paraseFloat function. This is necessary for them to be used in mathematical calculations. Line 8 calculates the cost and assigns it to the nCost variable, and finally the cost node is updated by setting the thisCost.nodeTypedValue equal to nCost.

Our second calculation function, updateTotals, appears in Example 10-7. It calculates the two values in the summary section, namely the number of items and the order total. The logic is similar to the updateCost function, except that it calls yet another function, sum, to calculate the sum.

function updateTotals()
{
  var numItemsNode =
    XDocument.DOM.selectSingleNode("//ns1:numItems")
  var nNumItems = sum("//ns1:quant")
  numItemsNode.nodeTypedValue = nNumItems

  var orderTotalNode =
    XDocument.DOM.selectSingleNode("//ns1:orderTotal")
  var nOrderTotal = sum("//ns1:cost")
  orderTotalNode.nodeTypedValue = nOrderTotal
}

It passes the sum function XPath expressions that are used to retrieve the nodes whose values need to be included in the sum. The XPath expressions used in this function use a double slash notation, as in //ns1:quant. This essentially means “all the ns1:quant elements in the document, no matter where they appear.”

The sum function is shown in Example 10-8. On line 3, it selects the nodes of interest using the selectNodes method of XDocument.DOM. In our previous examples, we used selectSingleNode because we only wanted to retrieve one node. The selectNodes method can be used instead to retrieve a list of nodes.

function sum(xpath)
{
  var nodeList = XDocument.DOM.selectNodes(xpath)
  var sum = 0
  var xmlNode

  while (xmlNode = nodeList.nextNode())
     if (xmlNode.nodeTypedValue > 0)
    sum += parseFloat(xmlNode.nodeTypedValue);

  return sum
}

The function then iterates through the list of nodes using a while loop that assigns one node after another to the xmlNode variable. The value of each node in the list is added to the sum.

In this example, we created a library of three functions that can be called from one or more other functions. You can add an unlimited number of such library functions to the script file. Unlike the functions that are specifically associated with fields and events, you can choose the names of your library functions.

We have seen how to select nodes from a document using the selectSingleNode and selectNodes methods along with XPath expressions. We have also seen how to update a node’s value, by assigning a value to the node’s nodeTypedValue property.

There may be cases where you also want to insert or delete nodes from the hierarchy. In most cases, the standard InfoPath user interface will take care of this for you, in that it creates the basic structure of the document by default. The user can use the standard InfoPath functionality for inserting and deleting repeating or optional elements.

However, you may want to customize this functionality. Suppose we want a facility that allows users to repeat a line item in the order form, so that they can more easily enter similar items. We have accomplished this in our order form example by placing a Repeat button within the item row and associating it with the script shown in Example 10-9.

function RepeatButton::OnClick(eventObj) {
  //assign the current item node to a variable
  var currentItem = eventObj.Source;
  //copy the current item node
  var copyOfItem = currentItem.cloneNode(true);
  //insert the copy before the current item node
  currentItem.parentNode.insertBefore(copyOfItem,currentItem);
}

Three simple lines of code are all that is needed to insert a copy of an item. On line 3, the current item (the one whose row contains the Repeat button that was clicked) is assigned to the variable currentItem. In this case, we use eventObj.Source to access this node.

When using the OnClick event, there is no eventObj.Site property as there was in the validation and calculation examples. In its place, the Source property retrieves the node that directly contains the button. In this case, it is the item element because the button appears within an item’s row.

Line 5 assigns a copy of the current item node to the variable copyOfItem. Finally, line 7 inserts the copy directly before the current item row. The parentNode property of the current item is used to access the item’s parent, namely the items node. The insertBefore method is then used to insert the current item as a child of items.

This chapter has provided an overview of InfoPath scripts and how they can be used to query and modify XML documents. In addition to these features, there are a number of other InfoPath capabilities that were not covered in detail in this chapter. They include:

A set of examples is provided with InfoPath. They can be found in the directory in which Microsoft Office is installed, in the OFFICE11SAMPLESINFOPATH subdirectory. Now that you have read this chapter, you will be in a good position to understand these examples and reuse parts of them in your own forms.