Show All

# Structural editing in the Structural Editing developer sample form

Structural editing in a Microsoft Office InfoPath 2003 form occurs when a user is filling out a form, and the type of editing actions that the user performs results in a structural change to the form's underlying XML document. Structural changes involve inserting or removing elements and attributes in the underlying XML document that the form is bound to. For example, in the Structural Editing developer sample form, structural changes are made when a user inserts or removes items from the Parts table or the Notes bulleted list.

Structural editing controls have predetermined editing actions that can be associated with toolbar buttons and menu items in InfoPath user interface areas. The Commands dialog box that is available from a structural editing control's Properties dialog box allows you to choose which editing actions of the control are available to users, which user interface area they appear in, and the labels that are used for the associated button or menu items. The structural editing controls used in this sample form include a repeating table and a bulleted list.

Structural editing can be implemented by using an InfoPath structural editing control, or by using scripting code to directly manipulate the data contained in the form's underlying XML document. If the form includes a control such as a repeating section that is bound to the modified (inserted or deleted) data, the data displayed in the form will be updated automatically.

Using controls for structural editing

When you drag a structural editing control onto a form while in design mode and then bind that control to a field or group, InfoPath will create an entry in the form definition (.xsf) file that specifies the editing component, the XML field or group that the editing component is bound to, and the XML fragment to use when inserting new items into the associated table, section, or list.

Editing components are the InfoPath implementation of some of the controls that are used in a form, and they are set in the component attribute of the editWith element in the .xsf file. The editing components used by InfoPath are xField, xTextList, xCollection, xOptional, xReplace, and xImage.

In the following example from the Structural Editing developer sample form, the editing element of the .xsf file contains information about the Parts table. The Parts table is implemented as a repeating table control that, in the .xsf file, corresponds to an editing component called xCollection; the xCollection editing component is listed in the component attribute of the editWith element. The editWith element contains a child element named fragmentToInsert, which contains a child element named chooseFragment. The chooseFragment element contains the XML fragment that will be inserted in the source XML document when a user chooses to add an item to the Parts table.

    <xsf:editing>
       <xsf:xmlToEdit name="1"
          item="/invoice/list/item"
          container="/invoice">
          <xsf:editWith caption="item" component="xCollection"
             xd:autogeneration="template">
             <xsf:fragmentToInsert>
                <xsf:chooseFragment parent="list">
                   <item>
                      <partNumber></partNumber>
                      <partDescription></partDescription>
                      <unitPrice></unitPrice>
                      <quantity></quantity>
                      <discount>0</discount>
                      <netDiscount>0</netDiscount>
                      <total>0</total>
                   </item>

    						</xsf:chooseFragment>

    						</xsf:fragmentToInsert>

    						</xsf:editWith>
       </xsf:xmlToEdit>
       ...
    </xsf:editing>

Using script for structural editing

Script editing in an InfoPath form occurs when a user is filling out a form, and the types of editing actions that the user can perform are determined by custom scripting code written by form developers using Microsoft Script Editor (MSE). For example, if an item in the Structural Editing developer sample form is selected in the Part Catalog custom task pane and the Add To Invoice button is clicked, a new row containing part data is added to the Parts table by making a call to the InsertPartFromCatalog custom function.

Note InfoPath supports writing script in Microsoft VBScript and Microsoft JScript. However, you cannot mix the scripting languages used within a single form.

The InsertPartFromCatalog custom function in the Structural Editing developer sample form's script.js script file, which is shown below, contains the scripting code that is used to insert the item selected by the user into the form's source XML document. The function first obtains the XML DOM corresponding to the form definition (.xsf) file using the DOM property of the Solution object, which is accessed through the XDocument object. It then uses the standard XML DOM method selectSingleNode to obtain the XML fragment to be inserted. Next, it modifies the appropriate fields in the fragment to correspond to the selected items in the custom task pane. Finally, it inserts the fragment into the source XML document using the DOM property of the XDocument object, and the standard XML DOM methods selectSingleNode and appendChild.

    function InsertPartFromCatalog
       (strPartNumber, strPartDescription, intUnitPrice)
    {
       var objFragmentToInsert = null;

       // Get the XML fragment to insert from the manifest.xsf.
       objFragmentToInsert = XDocument.Solution.DOM
          .documentElement.selectSingleNode
          ("//xsf:view[@name='View']//xsf:xmlToEdit[@item='/invoice/list/item']" +
          "/xsf:editWith[@component='xCollection']/xsf:fragmentToInsert/
          xsf:chooseFragment[@parent='list']/*[1]");

       // Make a copy of the fragment and update the fields with the
       // values from the catalog. Any changes to the fragment are
       // made before inserting it into the document so that the
       // insertion can be undone with a single Undo.
       objFragmentToInsert = objFragmentToInsert.cloneNode(true);
       objFragmentToInsert.selectSingleNode("partNumber").text = strPartNumber;
       objFragmentToInsert.selectSingleNode("partDescription").text = strPartDescription;
       objFragmentToInsert.selectSingleNode("unitPrice").text = intUnitPrice;

       // Insert the XML fragment into the document.
       XDocument.DOM.selectSingleNode("/invoice/list")
          .appendChild(objFragmentToInsert);
    }

As shown in the following example, the InsertPartFromCatalog custom function is called from the Part Catalog custom task pane by using the AddPartToInvoice custom function that is implemented in the code for the custom task pane. This function uses the Extension property of the XDocument object to access the custom functions contained in the script.js script file and call the InsertPartFromCatalog custom function when a user clicks the Add To Invoice button.

    function AddPartToInvoice(objPart)
    {
       // Call the insertPartFromCatalog function in the business logic, passing
       // the details for the part.
       window.external.Window.XDocument.Extension.InsertPartFromCatalog
          (objPart.PartNumber, objPart.PartDescription, objPart.UnitCost);
    }

©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