Lab 11: Customizing Merge Forms in InfoPath 2003

Article
07/11/2006

Microsoft Corporation

August 2004

Applies to:
Microsoft® Office InfoPath™ 2003 Service Pack (SP) 1

Summary: Learn how to add custom merge forms behavior to a form template. (7 printed pages)

Download the odc_INF03_Labs.exe sample file.

Prerequisites
Scenario
Lab Objective
Exercise 1: Enable Custom Merge in an InfoPath Form Template
Exercise 2: Author Custom Merge Using Form Code
Exercise 3: Verifying the Custom Merge
Conclusion

Prerequisites

Access to the Microsoft Office InfoPath 2003 Software Development Kit (SDK)
Access to two support files: Lab11Template.xsn and Lab11Report.xml

Scenario

Sales managers at Contoso have several sales representatives who report to them. A Sales manager will want to create a roll-up report by merging several sales report forms. Form developers can customize the behavior of merge forms to best meet the needs of the sales managers who are doing the rollup. This can be done either through form code or through a custom transform.

Lab Objective

In this lab, you will learn how to do the following:

Enable custom merges in an InfoPath form template.
Create custom merges using form code.
Preview the form to verify the custom merge.
Attach a custom merge transform to an InfoPath form template.

Exercise 1: Enable Custom Merge in an InfoPath Form Template

In this exercise, you start developing the form from an existing form template and configure it to customize merge forms by using form code. This exercise walks through the steps to prepare the form template for writing form code.

Open an Existing Form

Add custom merge functionality to an existing form template.

To open an existing form

Start InfoPath.
Click Fill Out a Form and then, click Design a Form.
On the Design a Form task pane, click On My Computer.
On the Open in Design Mode dialog box, locate the folder where you installed the training files, and then double-click the Lab 11 folder.
Select Lab11Template.xsn, and then click Open.

The Contoso sales report form opens in design mode.

Extract Form Files

You must perform manual editing of some of the files so next you must extract the form files.

To extract form files

On the File menu, click Extract Form Files.
Select a Folder and click OK.
On the File menu, click Close.

Configuring importParameters Within Manifest.xsf

Now that you extracted the form files, you can modify the manifest.xsf to configure Merge Forms. The definition of Merge Forms within the manifest is controlled by the importParameters section. This section determines:

Whether to enable Merge Forms for the form template, as specified by the enabled attribute.
Whether you can customize Merge Forms through form code in the OnMergeRequest event handler, as specified by the useScriptHandler attribute.
What custom transforms to apply to forms upon merging, as defined by importSource elements. (Optional)

The following is an example of the useScriptHandler attribute as it is used in the importParameters element:

<xsf:importParameters
   enabled="yes"
   useScriptHandler="yes">
   <xsf:importSource
      name="MySource"
      schema="MySchema.xsd"
      transform="schematransform.xslt"/>
   <xsf:importSource
      name="MySource2"
      schema="MySchema2.xsd"
      transform="schematransform2.xslt"/>
</xsf:importParameters>

To set the useScriptHandler attribute in the Manifest.xsf

Navigate to the folder that you chose in Step 2 in the previous exercise.
Open the manifest.xsf file in Notepad or another text editor.
Add the useScriptHandler=yes attribute to the importParameters element.

The importParameters element should now be as follows:

<xsf:importParameters enabled="yes" useScriptHandler="yes">

Save changes to the manifest.xsf file.

Adding OnMergeRequest to the Script File

After setting the useScriptHandler attribute in the manifest.xsf, InfoPath expects that the form code contains an OnMergeRequest event handler.

Note If you prefer to use managed code, skip the next procedure and continue to Exercise 2. You need to use the following initial code:

[InfoPathEventHandler(EventType=InfoPathEventType.OnMergeRequest)]

public void OnMergeRequest(MergeEvent e)

{

e.XDocument.ImportDOM(e.DOM);

e.ReturnStatus = true;

}

Add the OnMergeRequest event to the form

Right-click the manifest.xsf and choose Design to open the form template in InfoPath's design mode.
On the Tools menu, point to Programming, and then click Microsoft Script Editor.

The Microsoft Script Editor (MSE) starts.

Copy the following code:

function XDocument::OnMergeRequest(eventObj)
{
   XDocument.ImportDOM(eventObj.DOM);
   eventObj.ReturnStatus = true;
}

In the Microsoft Script Editor, place the cursor at the bottom of the script file and paste the code from Step 3 and then click Save.

Exercise 2: Author Custom Merge Using Form Code

The form template is now configured for a custom merge. The current behavior mimics the default behavior of merge forms. To customize the merge forms behavior, modify the code in the OnMergeRequest event.

Modify the OnMergeRequest event to the form

Right-click the manifest.xsf and choose Design to open the form template in design mode.

Note To use managed code, replace Step 1 with the instructions in Lab 15: Managed Code Business Logic in InfoPath 2003. In the Microsoft Office Project Wizard, on the Select a Form Template for Your Application page, choose Open existing form template. You will need to write equivalent form code to that in Step 3 using C#.
On the Tools menu, point to Programming, and then click Microsoft Script Editor.

The Microsoft Script Editor (MSE) starts.

Copy the following code:

    // This OnMergeRequest event will perform the following logic:
    // For each customer, do:
    //   1. If Customer Name doesn't match, insert customer
    //   2. If Customer Name matches, insert items.
    //   3. If Customer Name matches, concatenate Notes, 
    //      prepending bolded Sales Representative name.
    eventObj.DOM.setProperty("SelectionNamespaces",
        'xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xhtml=
        "http://www.w3.org/1999/xhtml"
        xmlns:my="https://schemas.microsoft.com/office/infopath/2003/myXSD/2004-01-19T21:16:49" 
        xmlns:xd="https://schemas.microsoft.com/office/infopath/2003"');

    var oSrcCustomers = eventObj.DOM.selectNodes("//my:customer");
    var oTrgContainer = XDocument.DOM.selectSingleNode("my:myFields//my:customerContainer");
    var strSrcRepName = eventObj.DOM.selectSingleNode("my:myFields//my:salesRepresentative").text;

    // Loop through the customers
    for(var i = 0; i < oSrcCustomers.length; i++)
    {
        var oSrcCustomer = oSrcCustomers.nextNode();                
        var strSrcCustomerName = oSrcCustomer.selectSingleNode("my:customerName").text;
        var oTrgCustomer = null;
        if (strSrcCustomerName) 
        {
            var strXPathFilter = "//my:customer[//my:customerName=\"" + strSrcCustomerName + "\"]";
            oTrgCustomer = XDocument.DOM.selectSingleNode(strXPathFilter);
        } // else, goes to Step 1.

        if (!oTrgCustomer) 
        {
            // Step 1.
            oTrgContainer.appendChild(oSrcCustomer.cloneNode(true));            
        }
        else
        {
            // Step 2.
            var oSrcItems = oSrcCustomer.selectNodes("my:itemsContainer//my:items");
            for(var j = 0; j < oSrcItems.length; j++)
            {
                var oSrcItem = oSrcItems.nextNode().cloneNode(true);
                oTrgCustomer.selectSingleNode("my:itemsContainer").appendChild(oSrcItem);
            }

            // Step 3.
            oTrgNotes = oTrgCustomer.selectSingleNode("my:notesContainer//my:notes");

            // Add xhtml elements
            var oHR = XDocument.DOM.createNode(1, "hr", "http://www.w3.org/1999/xhtml");
            oTrgNotes.appendChild(oHR);         

            // Prepend the source notes with bolded sales rep name
            if (strSrcRepName)
            {
                var oDiv = XDocument.DOM.createNode(1, "div", "http://www.w3.org/1999/xhtml");
                var oBold = XDocument.DOM.createNode(1, "strong", "http://www.w3.org/1999/xhtml");
                oBold.text = strSrcRepName + ":";
                oDiv.appendChild(oBold);
                oTrgNotes.appendChild(oDiv);
            }

            // Now copy the Notes from source to target
            var oSrcNotes = oSrcCustomer.selectSingleNode("my:notesContainer//my:notes").cloneNode(true);
            while (oSrcNotes.hasChildNodes())
            {
                oTrgNotes.appendChild(oSrcNotes.firstChild);
            }
        }
    }

    // The call to XDocument.ImportDOM is replaced by the above custom merge form code.
    eventObj.ReturnStatus = true;

In the Microsoft Script Editor, select the following form code in the script file and paste the code from Step 3.
```
   XDocument.ImportDOM(eventObj.DOM);
   eventObj.ReturnStatus = true;
```
To save your changes in MSE, click Save.
To save your changes to the form template in InfoPath, on the File menu, click Save.

Exercise 3: Verifying the Custom Merge

To verify your changes and their appearance, verify the custom merge.

To open the form

Start InfoPath.
Click Open a form, click Fill Out a Form, and then click Open.
On the Open dialog box, go to the folder that you saved the form template to from Exercise 2.
Select manifest.xsf, and then click Open.

The Contoso sales report form opens in InfoPath. Once you open the form, you can fill it out.

To verify the custom merge

On the File menu, click Merge Forms.
On the Merge Forms dialog box, locate and open Lab11Report.xml.

Note You find this file in the Lab 11 folder, in the directory where you installed your training files.
To merge the data in the Lab11Report.xml form with your latest form, click Merge.

Optional Exercise: Using the Merge Forms SDK Sample

In InfoPath, you can create custom merge forms behavior using transforms and merge annotations. You can use this custom transform either in conjunction with the OnMergeEvent or on its own. To gain a deeper understanding of how to use and create custom merge transforms, see About the Merge Forms Developer Sample Form in the Microsoft Office InfoPath 2003 Software Development Kit (SDK).

Conclusion

After completing this lab, you should know how to add custom merge functionality to an InfoPath form template through form code, custom transforms, or a combination of the two methods. By extending the exercises learned here, you can add rich custom merging to your form templates.