InfoPath stores all the relevant information about a form template in the form definition file, called manifest.xsf. This file is the core file of an InfoPath template and holds information about the document schema, views, business logic, event handlers, form metadata, and deployment information.

When viewing the XML structure of this file in a text editor, you will find many elements that hold information you have entered in InfoPath Designer. Listing 15-1 shows a complete XSF file for the Conference Room Booking example form. Some of the subelements have been omitted to increase readability.

<?xml version="1.0" encoding="UTF-8"?>
<xsf:xDocumentClass trustSetting="automatic"
                    trustLevel="restricted"
                    solutionFormatVersion="3.0.0.0"
                    solutionVersion="1.0.0.16" productVersion="14.0.0"
                    publishUrl="C:FormsEquipmentRequest.xsn"
                    name="urn:schemas-microsoft-com:office:infopath:
                          EquipmentRequest:-myXSD-2009-09-22T18-21-06"
                    xmlns:xsf="http://schemas.microsoft.com/office/
                               infopath/2003/solutionDefinition"... >
    <xsf:package>
        <xsf:files>
            <xsf:file name="myschema.xsd">
               <xsf:property name="namespace" type="string"
                    value="http://schemas.microsoft.com/office/

infoapth/2003/myXSD/2010_01_20T22:54:17"> </xsf:property>
               <xsf:property name="editability" type="string" value="full">
               </xsf:property>
               <xsf:property name="rootElement" type="string" value="RoomBooking">
               </xsf:property>
               <xsf:property name="useOnDemandAlgorithm" type="string" value="yes">
               </xsf:property>
            </xsf:file>
            <xsf:file name="template.xml"></xsf:file>
            <xsf:file name="sampledata.xml">...</xsf:file>
           <xsf:file name="view1.xsl">...</xsf:file>
           <xsf:file name="view2.xsl">...</xsf:file>
           <xsf:file name="upgrade.xsl"></xsf:file>
      </xsf:files>
     </xsf:package>
    <xsf:importParameters enabled="yes"></xsf:importParameters>
    <xsf:documentVersionUpgrade>
        <xsf:useTransform transform="upgrade.xsl" minVersionToUpgrade="0.0.0.0"
                          maxVersionToUpgrade="1.0.0.15"></xsf:useTransform>
    </xsf:documentVersionUpgrade>
    <xsf:extensions>
        <xsf:extension name="SolutionDefinitionExtensions">
            <xsf2:solutionDefinition runtimeCompatibility="client server"
                                     allowClientOnlyCode="no">
                <xsf2:offline openIfQueryFails="yes" cacheQueries="yes">
                </xsf2:offline>
                <xsf2:server isPreSubmitPostBackEnabled="no"
                             isMobileEnabled="no" formLocale="en-US">
               </xsf2:server>
                <xsf2:solutionPropertiesExtension branch="share">
                    <xsf2:share formName="test"
                                path="C:UsersAdministratorDocuments	est.xsn"
                                accessPath="">
                    </xsf2:share>
                </xsf2:solutionPropertiesExtension>
               <xsf2:viewsExtension>
                   <xsf2:viewExtension ref="view2" readOnly="yes" clientOnly="no">
                   </xsf2:viewExtension>
               </xsf2:viewsExtension>
            </xsf2:solutionDefinition>
        </xsf:extension>
    </xsf:extensions>
    <xsf:views default="View 1">
        <xsf:view showMenuItem="yes" name=" View 1" caption=" View 1">
        ...
        </xsf:view>
        <xsf:view showMenuItem="yes" name="Readonly" caption="Readonly">
        ...
        </xsf:view>
    </xsf:views>
    <xsf:applicationParameters application="InfoPath Design Mode">
        <xsf:solutionProperties fullyEditableNamespace="http://schemas.microsoft.com/office/infopath/2003/myXSD/2009-09-22T18:21:06" lastOpenView="view1.xsl" lastVersionNeedingTransform="1.0.0.15"></xsf:solutionProperties>

</xsf:applicationParameters>
    <xsf:documentSchemas>
        <xsf:documentSchema rootSchema="yes" location="http://schemas.microsoft.com/office/infopath /2003/myXSD/2009-09-22T18:21:06 myschema.xsd"></xsf:documentSchema>
    </xsf:documentSchemas>
    <xsf:fileNew>
        <xsf:initialXmlDocument caption="EquipmentRequest" href="template.xml">
        </xsf:initialXmlDocument>
    </xsf:fileNew>
    <xsf:submit caption="Submit" disableMenuItem="no" onAfterSubmit="close" showStatusDialog="no">
        <xsf:submitToHostAdapter name="Main submit" submitAllowed="yes">
        </xsf:submitToHostAdapter>
        <xsf:errorMessage>The form cannot be submitted because of an error.</xsf:errorMessage>
    </xsf:submit>
    <xsf:ruleSets>
        <xsf:ruleSet name="ruleSet_1">
            <xsf:rule caption="Send" isEnabled="yes">
                <xsf:assignmentAction targetField="my:readonly" expression="&quot;true&quot;">
                </xsf:assignmentAction>
                <xsf:submitAction adapter="Main submit"></xsf:submitAction>
                <xsf:closeDocumentAction promptToSaveChanges="no"></xsf:closeDocumentAction>
            </xsf:rule>
        </xsf:ruleSet>
    </xsf:ruleSets>
</xsf:xDocumentClass>

You can find the following important information in the manifest file:

Every form template has a schema file (.xsd) that prescribes the data structure expected by this form template. The schema file is expressed in XML Schema Definition (XSD), as defined by the W3C organization.

InfoPath validates every XML file to be rendered by the specified form template against this schema. This makes designing the schema very important, especially when the XML data files are manipulated outside of the InfoPath and Forms Services environments. If the XML is invalid according to the schema, the form cannot be displayed.

Listing 15-5 shows the schema file from the Conference Room Booking example. The second line contains a very important definition: the target namespace. This is the namespace to which all the elements and attributes belong. During validation of XML data files, InfoPath verifies that all the elements and attributes in the XML instance exist within the declared namespace.

In the example form data file (in Listing 15-8), you will see that the namespace declaration for the namespace my is exactly the targetNamespace of the schema. The other namespaces used in the schema define the XML schema namespace that contains all schema elements and some additional InfoPath schema extensions.

InfoPath uses element references to structure the schema. Starting at the root node, InfoPath creates complexType elements containing all elements at that node. Each element is described using element references pointing to elements, which are defined at the root element of the schema. This enhances readability of the schema and reusability of the elements.

Looking at the elements, you can see that InfoPath created some simpleType definitions, such as requiredString. This is used to implement the "Cannot be blank" check box in the field properties dialog in InfoPath Editor. This string extends the basic string format of XML Schema using a restriction, saying that the element has a minimum length of 1. You need to understand the difference between this and the minOccurs attribute used in the element descriptions. minOccurs tells the XML parser how often an element may be present in the XML. If you define the FirstName element with minOccurs=1, you are only specifying that this XML element is mandatory. However, the value of the element could still be empty.

Another important related attribute is the nillable attribute. This is usually used for date and time fields, as it allows an element to set the attribute nillable=true. Because a date element always requires the content to be a valid date, this is the only way to create empty date fields. Otherwise, if you entered an empty string into the date element, the validation of the XML would fail. An empty date can thus be created in the XML as <my:Date nil='true'></my:Date>.

<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<xsd:schema targetNamespace="http://schemas.microsoft.com/office/infopath/2003/myXSD/2009-09-29T22:54:17" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:my="http://schemas.microsoft.com/office/infopath/2003/myXSD/2009-09-29T22:54:17" xmlns:xd="http://schemas.microsoft.com/office/infopath/2003" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <xsd:element name="RoomBooking">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="my:UserInformation" minOccurs="0"/>
                <xsd:element ref="my:Schedule" minOccurs="0"/>
                <xsd:element ref="my:Hardware" minOccurs="0"/>
                <xsd:element ref="my:Catering" minOccurs="0"/>
                <xsd:element ref="my:Comments" minOccurs="0"/>
                <xsd:element ref="my:readonly" minOccurs="0"/>
            </xsd:sequence>
            <xsd:anyAttribute processContents="lax"
                              namespace="http://www.w3.org/XML/1998/namespace"/>
        </xsd:complexType>
    </xsd:element>

    <xsd:element name="UserInformation">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="my:FirstName" minOccurs="0"/>
                <xsd:element ref="my:LastName" minOccurs="0"/>
                <xsd:element ref="my:Email" minOccurs="0"/>
                <xsd:element ref="my:Telephone" minOccurs="0"/>
            </xsd:sequence>
        </xsd:complexType>

</xsd:element>
    <xsd:element name="FirstName" type="my:requiredString"/>
    <xsd:element name="LastName" type="my:requiredString"/>
    <xsd:element name="Email" type="xsd:string"/>
    <xsd:element name="Telephone" type="xsd:string"/>

    <xsd:element name="Schedule">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="my:Room" minOccurs="0"/>
                <xsd:element ref="my:Date" minOccurs="0"/>
                <xsd:element ref="my:TimeBegin" minOccurs="0"/>
                <xsd:element ref="my:TimeEnd" minOccurs="0"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="Room" type="xsd:string"/>
    <xsd:element name="Date" nillable="true" type="xsd:date"/>
    <xsd:element name="TimeBegin" nillable="true" type="xsd:time"/>
    <xsd:element name="TimeEnd" type="xsd:string"/>

    <xsd:element name="Hardware">
        <xsd:complexType>
            <xsd:sequence>
                <xsd:element ref="my:DataProjector" minOccurs="0"/>
                <xsd:element ref="my:Microphone" minOccurs="0"/>
                <xsd:element ref="my:Notebook" minOccurs="0"/>
                <xsd:element ref="my:Speakers" minOccurs="0"/>
                <xsd:element ref="my:VideoConferencing" minOccurs="0"/>
            </xsd:sequence>
        </xsd:complexType>
    </xsd:element>
    <xsd:element name="DataProjector" nillable="true" type="xsd:boolean"/>
    <xsd:element name="Microphone" nillable="true" type="xsd:boolean"/>
    <xsd:element name="Notebook" nillable="true" type="xsd:boolean"/>
    <xsd:element name="Speakers" nillable="true" type="xsd:boolean"/>
    <xsd:element name="VideoConferencing" nillable="true" type="xsd:boolean"/>

...

    <xsd:element name="readonly" nillable="true" type="xsd:boolean"/>

    <xsd:simpleType name="requiredString">
        <xsd:restriction base="xsd:string">
            <xsd:minLength value="1"/>
        </xsd:restriction>
    </xsd:simpleType>

    <xsd:simpleType name="requiredAnyURI">
        <xsd:restriction base="xsd:anyURI">
            <xsd:minLength value="1"/>
        </xsd:restriction>
    </xsd:simpleType>

    <xsd:simpleType name="requiredBase64Binary">
        <xsd:restriction base="xsd:base64Binary">
            <xsd:minLength value="1"/>
        </xsd:restriction>
    </xsd:simpleType>
</xsd:schema>

> xsd.exe <schemafile>.xsd /classes /language:CS /outputdir:<output directory>

using System.Xml.Serialization;
System.IO.StreamReader str = new System.IO.StreamReader("example.xml");
XmlSerializer xSerializer = new XmlSerializer(typeof(ConferenceBooking));
ConferenceBooking res = (ConferenceBooking) xSerializer.Deserialize(str);

Each view in the form template is defined by an XSL stylesheet file, which comprises all the relevant information for displaying the view. To render a view, the selected XML data file will be transformed into an HTML view via XSLT processing.

Listing 15-6 shows the body of such a view definition. For a clearer perspective, the HTML content, style definitions, and namespace definitions have been removed.

<?xml version="1.0" encoding="UTF-8"?>
<xsl:stylesheet version="1.0" xmlns:"...">
    <xsl:output method="html" indent="no"/>
    <xsl:template match="my:RoomBooking">
        <html>
            <head>
                <meta content="text/html" http-equiv="Content-Type"></meta>
                <style controlStyle="controlStyle">...</style>
                <style themeStyle="urn:office.microsoft.com:themeOffice">...</style>
                <style languageStyle="languageStyle">...</style>
            </head>
            <body style="BACKGROUND-COLOR: #ffffff; COLOR: #000000">
            ...
            </body>
        </html>
     </xsl:template>
</xsl:stylesheet>

The stylesheet defines one template rule that applies to the root element of the XSD schema. In the example you can see that the match attribute points to the RoomBooking node, which is the root element in our example. Within this template, HTML defines the display behavior. To insert the XML information from the data file, XSLT instructions are used within the template. The following snippet (in Listing 15-7) demonstrates how the drop-down list for the room is defined as a table element within the HTML layout. An XSLT select element is inserted, and the attributes value and selected are supplied from the XML data using XSLT instructions.

<td class="xdTableComponent" style="PADDING-BOTTOM: 1px; VERTICAL-ALIGN: middle; PADDING-TOP: 1px">
    <div>
        <select class="xdComboBox xdBehavior_Select" title="" size="1" tabIndex="0" xd:xctname="dropdown" xd:CtrlId="CTRL19" xd:binding="my:Schedule/my:Room" xd:boundProp="value" style="WIDTH: 100%">
            <xsl:attribute name="value">
                <xsl:value-of select="my:Schedule/my:Room"/>
            </xsl:attribute>
            <option value="">
                <xsl:if test="my:Schedule/my:Room=&quot;&quot;">
                    <xsl:attribute name="selected">selected</xsl:attribute>
                </xsl:if>
            </option>
        </select>
    </div>
</td>

As you can see, the structure of XSL views is quite easy to follow and allows you to make changes to the layout or the XSL instructions. Nevertheless, manually editing views is very time consuming and requires you to deal with some Microsoft-specific schemas.

Every form template contains two XML files: sampledata.xml and template.xml. The sampledata.xml file contains all the elements of the form with their default values, which were specified when the form was designed. The template.xml file represents an XML template that is used as a template for creating new documents. Although at first sight these files may not seem to be very useful, for developers this is not so. The template file, for example, can be used to create new document instances from custom code. If you wish to dynamically set default values for your forms, you can edit sampledata.xml from within your code.

The structure of the XML files is the same as the structure of form data files, described next.

When you start to design a new form, you can choose the type of template you want to design. Some advanced templates will require you to enable browser support in your form template. To enable browser support, go to File

Depending on the compatibility setting, some features will be hidden or deactivated in the relevant dialogs. For example, the multiline feature of text boxes is limited when you work with browser-enabled forms. Figure 15-11 shows the different options for templates designed for InfoPath Editor (on the left) and InfoPath Forms Services (on the right). Therefore, you should always set the compatibility before starting to design your form template. This way you ensure that you are only using available features.

Figure 15.10. Enabling browser compatibility

Figure 15.11. Different properties for InfoPath forms (left) and browser-enabled forms (right)

After you have set the compatibility to Web Browser Form, you will find a new category called Web Browser in your Form Options dialog when you reopen it (Figure 15-13). Here you can set advanced options that change the browser interface, which is shown in Figure 15-14. You can select the commands you wish to display to the user when editing the form. Furthermore, you can select alternative toolbars in case the ribbon bar is not available, and set the language that will be used for displaying the commands and dialogs.

Figure 15.12. UI in InfoPath Forms Services

Figure 15.13. Setting UI options

You need to specify the destination for the data entered into the form. Submitting the form will trigger Forms Services to run the validation checks on the form. All the validation rules must pass before the submit is allowed to proceed.

You can either specify submission using rules (i.e., you can add a button with an action rule and select the submit action) or you can use the submit options from the Data ribbon bar. In either case you need to specify a submit data connection as described previously. Most commonly you will use a connection to a SharePoint library, a SharePoint data connection, or the hosting environment. When specifying a SharePoint library, you need to provide the URL of the library and the file name for saving the form. The file name can be constructed using a formula. The hosting environment will be used when you want to programmatically access the form information from an ASP.NET application such as SharePoint application pages.

The submit options, as shown in Figure 15-14, allow you to specify the submit destination and the corresponding data connection. As an alternative, you could use code to programmatically handle the submit event.

Specifying submit options and using a button with action rules to submit the form differ in the way the submit action will be displayed to the users. If you are using submit options, the submit button will be displayed in the ribbon bar; however, placing a button in the form provides more flexibility and might be more intuitive for many users. You can also make use of the new image buttons, which allow you to customize button layout.

Figure 15.14. Setting submit options

To ensure that browser support is configured correctly, use the following checklist:

When you choose to publish the form template to a document library, the form template will be stored inside the document library in an invisible folder called Forms. The form template itself will be called template.xsn, irrespective of its original file name. A content type will then be created based on this XSN file, and assigned as a standard content type for the document library in question.

By default, when creating a new document library, either from the wizard or manually, only one content type is allowed per library. During publishing, InfoPath will overwrite this content type and set the form template as the default content type.

You can create new documents based on the published form template by clicking New Document on the library toolbar. Thus, this publishing option offers a quick method to create a document library with one InfoPath form assigned. This way you can provide a single form template per library, and you cannot reuse the published form template across multiple libraries.

Note

Although you can select the "Allow management of multiple content types" option from Form Library Settings

If you want to use your InfoPath template across multiple libraries, or use multiple form templates within one library, you need to publish your form template as a separate content type. When you do so, InfoPath Forms Services will create a new content type (or update an existing one if you choose this option) based on the form template. You will then be able to select this content type for your library in the list settings page. When you add the new content type to your library, users will be able to create new documents based on this form template by selecting New Document from the Documents ribbon.

In the Publishing wizard you will be asked to specify a location and file name for your form template (Figure 15-17). You can specify any document library within the site to which your content type will be published. However, the best location for your form templates is a library called Form Templates within your site. This library is available in every site and can be accessed by the path <Site URL>/FormServerTemplates.

Figure 15.17. Publishing a form template to SharePoint as a content type

As already mentioned in when talking about forms security earlier, whenever you wish to publish a fully trusted form to SharePoint, the form must be deployed by a farm administrator. Such forms are known as administrator-approved form templates. Of course, you can also deploy forms as administrator-approved form templates that don't require administrator approval. You might want to do this to unify your deployment when working with different types of form templates. However, the form templates will have to be deployed by a farm administrator in any case.

During publishing of an administrator-approved template you will be asked to enter the SharePoint URL, which will be saved in the published form template. After that, you must enter a network location or local file name where the template will be saved. A SharePoint administrator can now upload this published form to SharePoint via Central Administration. After uploading, the form must be enabled for the site collections where it is to be used.

In general, using administrator-approved templates requires the following:

In the "InfoPath Forms Services" section we will describe how you can manage form templates in SharePoint Central Administration and how you can deploy and activate your administrator-approved form templates.

Instead of directly publishing your form template to SharePoint or publishing it as an administrator-approved template, you can publish your template to a network location. In particular, if you are deploying your form template manually to the SharePoint server, or using any other method, such as including your form template into a solution, you can use this publishing method. Since publishing to a network connection does not require you to connect to the SharePoint server, this method will also work when you don't have access to the SharePoint server.

All the relevant settings that allow you to use your form within SharePoint will be established when you enable your template, meaning that you can use this method instead of the more complex SharePoint wizards. In development scenarios, on the other hand, running a wizard allows you to quickly publish new versions of your form. But when using this publishing method, make sure to take one of the following steps to make your form work in Forms Services:

Figure 15.18. Publishing to a network location: Alternative access path

stsadm.exe is the command-line utility used in previous SharePoint versions to administer SharePoint from the command line and for scripting batch files. Although its use will diminish in favor of PowerShell cmdlets, it is still supported by SharePoint 2010. Since it is widely used, we will show the most important commands. stsadm.exe is located in the bin folder of the SharePoint installation path: C:Program FilesCommon FilesMicrosoft SharedWeb Server Extensions14instsadm. To run the utility, you need to pass the parameter -o followed by the supported operation you wish to execute.

Working with InfoPath forms, the operations described in Table 15-2 are useful for uploading and installing form templates.

Using the preceding operations you could write a script such as the following to upload a new form template after deactivating and removing the prior version of the form. Instead of the file name, you can also use the <formid> to specify the form template.

STSADM.EXE -o DeActivateFormTemplate -url http://<servername> -filename <filename.xsn>
STSADM.EXE -o RemoveFormTemplate -filename <filename.xsn>
STSADM.EXE -o VerifyFormTemplate -filename <filename.xsn>
STSADM.EXE -o UploadFormTemplate -filename <filename.xsn>
STSADM.EXE -o ActivateFormTemplate -url http://<servername> -filename <filename.xsn>

As described in Chapter 9, SharePoint 2010 relies heavily on PowerShell cmdlets for administration tasks. The following cmdlets are relevant when working with InfoPath form templates. The table also lists the stsadm commands that have similar functions, to give users familiar with stsadm a quick cross-reference:

By analogy, with the stsadm commands shown in the table, the following script can be used to upload a new version of an InfoPath form, after deactivating and removing the prior version of the form:

Uninstall-SPInfoPathFormTemplate -Identity formName.xsn
Install-SPInfoPathFormTemplate -Path C:Form.xsn
Enable-SPInfoPathFormTemplate -Identity "FormTemplate.xsn" -Site "http://TestSite"

For code in your InfoPath project to be called, it needs to be tied to an event. Events can be added by clicking the event buttons in the development ribbon. Each event will be registered as a delegate in the InternalStartup method. The class EventManager is used to bind event handlers to the different events.

Events are divided into three categories: FormEvents, ControlEvents, and XmlEvents. Each of these categories is represented by an object of the same name. FormEvents are events that occur to the form, such as loading and saving. ControlEvents are events issued by special controls. For example, the ButtonEvent implements the Clicked event, which is handled as a control event. Whenever you add a button and want to handle the Clicked event using code, an event handler will be added to the ControlEvents.

Finally, XmlEvents are used for anything that happens to the underlying XML structure of your form—for example, when a field is changed. When changes are made to the XML data, events will be bubbled up through the data structure. Assume your schema has a group element group1 that contains a field element called test. Figure 15-21 shows the simple data schema for this example.

Figure 15.21. Simple data schema used for the events example

When you change the content of the field element test, the event handler of the test element will be called. After that, the Changed event of the group1 element will be raised. When working with XmlChange events, the XmlEventArgs object supplies detailed information about the change. You can retrieve the OldValue, which shows the value before the change, and the NewValue, which contains the value after the change. In addition, the member Site returns an XPathNavigator object that points to the element on which the change event is currently being handled. The element that is responsible for the change (in the preceding example, this is the test element) can be accessed using the sender object. This is also an XPathNavigator object that points to the element that was originally changed and caused the event to be passed upward through the hierarchy. Listing 15-12 shows how these events will be thrown. Each event simply displays a MessageBox that outputs the name of the event along with the name of the Site element and the name of the sender object. This example is built with an InfoPath Filler form template to keep it as simple as possible. The MessageBox is not available to web browser forms.

public partial class FormCode
{
    public void InternalStartup()
    {
        // Register events

EventManager.XmlEvents["/my:myFields"].Changed +=
                                  new XmlChangedEventHandler(myFields_Changed);
        EventManager.XmlEvents["/my:myFields/my:group1"].Changed +=
                                    new XmlChangedEventHandler(group1_Changed);
        EventManager.XmlEvents["/my:myFields/my:group1/my:test"].Changed +=
                                      new XmlChangedEventHandler(test_Changed);
    }

    public void group1_Changed(object sender, XmlEventArgs e)
    {
        // Show a message box about the changes
        MessageBox.Show("group1_Changed: Site=" + e.Site.Name + " sender=" +
             ((XPathNavigator)sender).Name + "from " + e.OldValue + " -> " +
             e.NewValue);
    }

    public void test_Changed(object sender, XmlEventArgs e)
    {
        MessageBox.Show("test_Changed: Site=" + e.Site.Name + " sender=" +
             ((XPathNavigator)sender).Name);
    }

    public void myFields_Changed(object sender, XmlEventArgs e)
    {
        MessageBox.Show("myFields_Changed: Site=" + e.Site.Name + " sender=" +
             ((XPathNavigator)sender).Name);
    }
}

Table 15-5 shows all events that are available in browser-enabled forms. When working with InfoPath Filler, some additional events are available.

When discussing events earlier, we encountered a very important class for working with XML data sources: XPathNavigator. This class provides cursor-based access to primary and secondary XML data sources of the InfoPath form and allows modification of the XML data structure. You can use XPathNavigator to navigate over the XML structure using move methods such as MoveToFirstChild or MoveToParent. The cursor of XPathNavigator will then be moved relative to its current node and point to a different node in the XML hierarchy. On the node to which the cursor is currently pointing, you can execute several methods to modify the data or retrieve information about that node. The property Name contains the name of the current node, and OuterXml will return the XML data for the current node from its opening to its closing tags, including its child nodes. InnerXml, on the other hand, returns the XML fragment that is contained within the current node, excluding the node itself. The property Value returns the string of the current node's value item, and the method SetValue allows you to set this value.

When working with InfoPath, navigating through the XML structure along the XPath axes is not very common, since you already know about your data structure. Most of the time you will want to directly select a node or node set to read or write fields in your data source. XPathNavigator offers two very useful methods for selecting nodes: Select and SelectSingleNode. Both methods select nodes according to the given XPath expression, but instead of returning an instance of XPathNodeIterator, SelectSingleNode returns the XPathNavigator object of the first node matching the XPath query. Thus, accessing a node in your form becomes very easy. All you need to do is right-click the node in the Fields pane in InfoPath Designer and select Copy XPath, as shown in Figure 15-22.

Figure 15.22. Copying the XPath of a field

This will create the XPath expression for selecting the node, which can then be copied into the Select method of the XPathNavigator object. To resolve the namespaces used in the form, the select methods also require an element implementing the IXmlNamespaceResolver interface. Fortunately, the NamespaceManager object of the XmlForm already implements this interface, and you can simply use the NamespaceManager property when calling the Select methods.

To access the XML data using XPathNavigator, you first need access to the data sources. XmlForm offers access to a DataSource through its DataSources property. As mentioned earlier, a form consists of one primary and several secondary data sources. The DataSources property contains all the data sources, including the main data source. In addition, MainDataSource provides direct access to the form's main data source. On any DataSource object, you can call the CreateNavigator method to obtain an XPathNavigator that can be used to access and manipulate the data source.

The following example shows a very common scenario, in which data is loaded from a web service into the main data source using XPathNavigator. A data connection to the SharePoint list Rooms was added to retrieve all the room entries in the list and load them into the Room drop-down list on the InfoPath form, which is shown in Figure 15-23.

Figure 15.23. Selecting rooms from a SharePoint list

The web service will be called during form loading, and a second data connection, called GetRoom, will be added. It will be queried when a user selects a room from the drop-down list, and will load the detailed information from the list for the selected room. Then the "RoomNumber" field will be filled from the web service response using XPathNavigator. Calling the "GetRoom" data connection and loading the "RoomNumber" will be done in the changed event that is bound to the Room field. So whenever someone edits the content of the Room field by selecting a room, this code will be executed.

using Microsoft.Office.InfoPath;
using System;
using System.Xml;
using System.Xml.XPath;

namespace RoomBooking_LoadingWebService
{
    public partial class FormCode
    {

        public void InternalStartup()
        {
            EventManager.XmlEvents["/my:RoomBooking/my:Schedule/my:Room"]
                          .Changed += new XmlChangedEventHandler(Room_Changed);
        }

        public void Room_Changed(object sender, XmlEventArgs e)
        {
            XPathNavigator form = MainDataSource.CreateNavigator();

            // Set parameter for web service request and query connection
            DataSources["GetRoom"].CreateNavigator().SelectSingleNode(
                  "/dfs:myFields/dfs:queryFields/q:SharePointListItem_RW/q:ID",
                  NamespaceManager).SetValue(e.NewValue);
            DataSources["GetRoom"].QueryConnection.Execute();

            // Create navigator on web service response
            XPathNavigator roomdata = DataSources["GetRoom"].CreateNavigator();

// Set fields with values from web service response
            XPathNavigator nodeRoomNumber = form.SelectSingleNode(
                "/my:RoomBooking/my:Schedule/my:RoomNumber", NamespaceManager);
            nodeRoomNumber.SetValue(roomdata.SelectSingleNode(
                "/dfs:myFields/dfs:dataFields/d:SharePointListItem_RW/d:RoomNumber",
                NamespaceManager).Value);
        }
    }
}

To maintain global state in browser-enabled forms, you can use the FormState property of XmlForm. Working with browser-enabled forms, this is the only way to persist data during a session. As with web pages, you cannot use member variables to maintain state, since they will not be persisted between requests. The FormState property will keep its values from the time the form is opened until it is closed.

FormState is an IDictionary object that holds user-defined key/value pairs of state variables. Both key and value can be any object, but generally strings are used for the key. The value can store objects that hold complex data. For convenience you might consider introducing a global member variable that leverages FormState by reading from and writing to FormState in the get and set methods. This gives you the ease of use of properties while still persisting data between requests.

Listing 15-14 shows how you can create a member variable using FormState, which can persist information across multiple events.

public string Username
{
    get
    {
        if (FormState["_username"] != null)
        {
            return (string)FormState["_username"];
        }
        else
        {
            return "";
        }
    }
    set
        {
            FormState["_username"] = value;
        }
    }
}

Forms are organized using views. You can also work with views in your form code. As described earlier, you can use the ViewSwitched event to react to the change of the current view. The XmlForm object contains useful information about views. First of all, you can use the CurrentView property to get the view that is currently active. In a web-based form template, the resulting View object contains a ViewInfo member with descriptive information about the view. In web forms, you can only access the Name of the view. To access all the available views for a form template, the ViewInfos member returns a list of ViewInfo objects. In addition, it holds the Default and Init properties, which return the default view and the initial view of the form.

If you wish to programmatically switch the view, you can use the SwitchView method of the ViewInfoCollection returned by ViewInfos to switch the view from the current view to the desired view.

During validation of a form, several errors in the form data can occur. For example, if you add a validation rule, the field will be displayed in red when the validation fails. In general, errors can arise when a form's XML schema is validated, when a custom validation rule fails, or when the error is added to the collection of errors from code. The XmlForm object keeps in the Errors property a collection of all errors that occurred. You can access individual Error objects from the list of errors, as with any other enumerable collection.

Each Error object contains detailed information about the error, (e.g., in the Name, Message, and DetailedMessage properties). The property FormErrorType specifies how the error was generated: through SchemaValidation, SystemGenerated or, UserDefined. Since an error always belongs to a node in the XML data that caused the error due to a failed validation, the property Site holds an XPathNavigator object that points to the affected node.

You can also add your own errors to the Errors collection using the Add method. This method expects an XPathNavigator pointing to the affected node, a name, and a message. Deleting errors from the list can also be done easily using the Delete method.

Using the Errors collection allows you to manage all the errors in your form that can eventuate during validation.

What was a painful configuration hazard in earlier versions of SharePoint has become effortless with SharePoint 2010: configuring the State Service. Since SharePoint relies on service applications to provide shared functionality, you don't have to deal with shared service providers any more. Simply run the Farm Configuration wizard from the Configuration Wizard section. On the second page are many service applications. Select State Service and complete the wizard.

Figure 15.24. State Service configuration

The State Service is required to store temporary data between related HTTP requests and thus keep the state of your forms. To store the data, a SQL database is used. By default, the data will be stored in the same database as the content database, and a single State Service instance will be shared among all components that require State Service. You can only change those advanced settings using PowerShell. SharePoint Central Administration does not provide any control other than enabling State Service using default settings.

Get-SPStateServiceApplication: Gets a list of State Service applications
New-SPStateServiceApplication: Creates a new State Service application
Set-SPStateServiceApplication: Sets parameters on a State Service application

SharePoint Central Administration contains a separate section for managing InfoPath Forms Services. It is located on the General Application Settings page. Besides management of form templates, data connection files, and a proxy for InfoPath forms, it also contains a link to the "Configuration of InfoPath Forms Services" settings.

Figure 15.25. Central Administration: Configuring InfoPath Forms Services

Without going into too much detail, we will briefly describe the most relevant settings in the configuration screen (Figure 15-25). Most of the settings are self explanatory.

The first section defines how browser-enabled forms deployed by users are handled in InfoPath Forms Services. If you select "Allow users to browser-enable form templates," you allow users to deploy browser-enabled forms. The next option allows browser-enabled user form templates to be displayed in the browser. If you don't select "Render form templates that are browser-enabled by users," users will still be able to deploy browser-enabled forms, but the forms will not be displayed in the browser. If you ever have trouble displaying a browser-enabled form, make sure that these options are set correctly.

If you want your users to access data from other domains using data connection files, you should check the "Allow cross-domain data access . . ." check box.

For any other settings, please refer to MSDN for detailed information here: http://technet.microsoft.com/en-us/library/cc262263(office.14).aspx.

For many common scenarios, the default settings in this dialog are appropriate.

Get-SPInfoPathFormsService:   Gets the InfoPath Forms Services settings for the farm
Set-SPInfoPathFormsService:    Sets parameters for InfoPath Forms Services settings

To integrate XmlFormView with your web page, you need to register the assembly Microsoft.Office.InfoPath.Server. Having done that, you can place the XmlFormView control in your ASPX markup, set some important parameters for the control, and bind events. The following listing shows the markup for an application page. The OnSubmitToHost attribute is bound to a method in the code-behind file. This code will be called when the form sends data to the hosting environment, using a submit data connection. Another attribute to note is the EditingStatus. This describes the editing state of the form and has three possible values: Init, Editing, and Closed. Use the Init state to hide the form during loading of the form and set it to Editing later on. In state Editing, the form is visible to the user. This is the only state in which the user can edit or view the form. When the form is closed, the common message "The form has been closed" will be displayed. If you have ever had an error in your form, you will be familiar with this message.

<%@ Page Language="C#" AutoEventWireup="true" CodeFile="ShowForm.aspx.cs" Inherits="ShowForm" EnableSessionState="True" %>
<%@ Register tagprefix="fv" namespace="Microsoft.Office.InfoPath.Server.Controls" assembly="Microsoft.Office.InfoPath.Server, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<%@ Register tagprefix="Server" namespace="Microsoft.Office.InfoPath" assembly="Microsoft.Office.InfoPath, Version=14.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c" %>
<html xmlns="http://www.w3.org/1999/xhtml">
    <head runat="server">
        <title>FormViews</title>
    </head>
    <body style="margin: 0px;overflow:auto;padding:20px">
        <form id="form1" runat="server" enctype="multipart/form-data">
            <fv:XmlFormView ID="formView" runat="server"
                            EditingStatus="Editing"
                            OnSubmitToHost="FormView_SubmitToHost"
                            Width="700px">
            </fv:XmlFormView>
        </form>
    </body>
</html>

To correctly display forms, XmlFormView needs to know the location of the form to display, the location of the form template used to render the form, and finally, the location for saved forms to be stored. The properties XmlLocation, XsnLocation, and SaveLocation are used to pass this information to the XmlFormView object.

When opening an existing form, the matching form template is contained in the manifest file and does not need to be specified. But when a new form is created, the form template needs to be specified. You can specify these parameters in the page markup as attributes or set the class properties directly inside your code-behind.

To display an XML form, you can use the following code in the On_Load method in the code-behind file of the previous example. In the following listing, depending on a request parameter, either an existing form will be loaded using the XmlLocation parameter or the template will be assigned by the XsnLocation if the request parameter action equals new.

using System;
using Microsoft.SharePoint;
using Microsoft.SharePoint.WebControls;
using Microsoft.Office.InfoPath.Server.Controls;

namespace com.apress.formviewdemo
{

    public partial class ShowForm : LayoutsPageBase
    {

        protected void Page_Load(object sender, EventArgs e)
        {
            string action = Request.Params["action"];
            if (action == "new")
            {
                // Set the template location for new forms
                String templateLib = "FormServerTemplates";
                String xsnName = "template.xsn";
                formView.XsnLocation = String.Format("{0}/{1}/{2}",
                              SPContext.Current.Web.Url, templateLib, xsnName);
            }
            else
            {
                // Set the XML location for an existing form
                String lib = "TestForms";
                String name = "example.xml";
                formView.XmlLocation = String.Format("{0}/{1}/{2}",
                                         SPContext.Current.Web.Url, lib, name);
            }
        }

        protected void FormView_SubmitToHost(object sender, SubmitToHostEventArgs e)
        {
            // Will be implemented later
        }
    }
}

Working with XmlFormView, you can access the XmlForm object and thus all the values and settings of the form described in the "Table 15-6 compares the two options for deploying forms with code.

Programming InfoPath Forms" section. Via the XmlForm property you can reach the properties DataSources, ViewInfos, FormState, and such from within the page that is hosting the form. The XmlForm object can be accessed whenever the code is run within one of the following event handlers, which enables a form to communicate with its hosting environment:

If you want to access the XmlForm object from another event on your page, you have to first call the method Data Bind of the XmlFormView object to ensure that the XmlForm object is adequately populated.

You can directly access fields inside your form using the XPathNavigator on the MainDataSource. This may be required when implementing your own OnSubmitToHost event where you wish to store the XML data into a library and build the file name using information within the form. Listing 15-17 shows how this can be done. To keep things clear, we have only implemented the OnSubmitToHost event, which was left blank in the previous example.

protected void FormView_SubmitToHost(object sender, SubmitToHostEventArgs e)
{
    SPWeb web = SPContext.Current.Web;
    web.AllowUnsafeUpdates = true;

    // Load the XML and save it as a byte array
    System.Xml.XPath.XPathNavigator navigator =
                            formView.XmlForm.MainDataSource.CreateNavigator();

Byte[] formBytes = System.Text.Encoding.UTF8.GetBytes(navigator.OuterXml);

    // Create XmlDocument from the form XML
    XmlDocument doc = new XmlDocument();
    XmlNamespaceManager nsm = new XmlNamespaceManager(doc.NameTable);
    nsm.AddNamespace("my", "http://schemas.microsoft.com/office/infopath/2003/myXSD/2009-09-29T22:54:17");
    doc.LoadXml(navigator.OuterXml);

    // Load name information from the XML
    XmlNode nodeLastName = doc.SelectSingleNode(
                        "/my:RoomBooking/my:UserInformation/my:LastName", nsm);
    string name = (nodeLastName != null) ? nodeLastName.InnerText : string.Empty;
    XmlNode nodeFirstName = doc.SelectSingleNode(
                       "/my:RoomBooking/my:UserInformation/my:FirstName", nsm);
    string firstname = (nodeFirstName != null) ?
                                          nodeFirstName.InnerText : string.Empty;

    // Generate file name
    string filename = String.Format("{0}{1}_{2}.xml", name, firstname,
                                            DateTime.Now.ToString("yyyyMMdd"));

    // Open library and save XML
    SPFolder formLibrary = web.GetFolder(LIBRARY_NAME);
    formLibrary.Files.Add(filename, formBytes);

    web.AllowUnsafeUpdates = false;
}

Using InfoPath forms in SharePoint and storing the forms in a forms library enables development of complex browser-based applications with a great user experience. The forms are well-integrated into SharePoint with the support of Forms Services, but all the information that was entered by the users is stored within the XML file. There seems to be no easy access from the SharePoint environment to this data. What if you want to create a view that shows all the room bookings for one particular room? Or what if you want to change single values in your XML file from SharePoint? Many of the great features SharePoint offers work with list columns but don't offer extensibility to access information within XML files.

To solve this problem, SharePoint and InfoPath support features called property promotion and property demotion. SharePoint allows you to define fields in your InfoPath form that will be automatically provided as a column in your SharePoint document library. SharePoint automatically propagates changes that are made in your document to the SharePoint column and vice versa. Property promotion involves extracting fields from XML documents and writing these values to columns in SharePoint document libraries. Property demotion, on the other hand, involves taking changes to the SharePoint column available in your XML form.

Property promotion and demotion work as follows: whenever a new or existing XML file is saved in the document library, SharePoint invokes a built-in XML parser on the XML file. When the document content type contains a column that maps a field in the XML document to a list column (via an XPath expression that is pointing to the XML field), this value will be promoted to the library. In the other situation, where the column in the library is updated, this XPath expression is used to demote the information to the XML file.

In the description of the XmlFormView earlier in this chapter, we showed a method to directly manipulate the form's XML structure, which could also be used to access form fields, but requires more effort.

Configuring Promotion/Demotion Using InfoPath

When you are using the InfoPath Publishing wizard to publish your form template to SharePoint, you will encounter the dialog shown in Figure 15-30. In this dialog, you can add property promotion and demotion using the Add... button in the upper area of the wizard. In the upcoming dialog you can select a field from your main data source and specify the column name within the document library. InfoPath Forms Services will then create the necessary columns in the document library and store the XPath link to the referenced nodes in the column definition. The lower area is used for Web Part connection parameters (described next).

Figure 15.30. Configuring property promotion and demotion

<?xml version="1.0" encoding="utf-8"?>
<List xmlns:ows="Microsoft SharePoint"
    Title="Order Requests"
    Direction="$Resources:Direction;"
    Url="OrderRequests" BaseType="1"
    EnableContentTypes="TRUE"
    AllowMultipleContentTypes="True"
    xmlns="http://schemas.microsoft.com/sharepoint/">
    <MetaData>
        <ContentTypes>
            <ContentType ID="0x01010100B3E78F42234547a580BDE72BCB3E650A" Name="Order Requests"
 Description="Request a new Order"
 Group="$Resources:Document_Content_Types" Version="1">
                <FieldRefs>
                    <FieldRef ID="{DDC3C6B7-C34A-4d5a-8355-DC4E81885C8D}"
                              Name="Title" />
          ...
                    <FieldRef ID="{6CE8A87B-0862-4d8d-891F-5CA9C16833D4}"
                              Name="Room" />
                    <FieldRef ID="{05F09611-7D5B-4bae-9FA5-3EC8402F7A00}"
                              Name="Date" />
                    <FieldRef ID="{2C1B30B7-AADC-434b-9F82-D70639B59AB1}"
                              Name="TimeBegin" />
                    <FieldRef ID="{52BBFDF2-3176-43d7-A4D2-EFFA78CCED33}"
                              Name="TimeEnd" />
                </FieldRefs>
                <DocumentTemplate TargetName="/FormServerTemplates/RoomBooking.xsn"
                />
            </ContentType>
        </ContentTypes>
        <Fields>
      ...
            <Field ID="{6CE8A87B-0862-4d8d-891F-5CA9C16833D4}" ShowInNewForm="FALSE" Type="Text" Name="Room" DisplayName="Room" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="Room" Node="/my:RoomBooking/my:Schedule/my:Room" ></Field>
            <Field ID="{05F09611-7D5B-4bae-9FA5-3EC8402F7A00}" ShowInNewForm="FALSE" Type="DateTime" Name="Date" DisplayName="Date"

SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="Date" Node="/my:RoomBooking/my:Schedule/my:Date" ></Field>
            <Field ID="{2C1B30B7-AADC-434b-9F82-D70639B59AB1}" ShowInNewForm="FALSE" Type="DateTime" Name="TimeBegin" DisplayName="TimeBegin" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="TimeBegin" Node="/my:RoomBooking/my:Schedule/my:TimeBegin" ></Field>
            <Field ID="{52BBFDF2-3176-43d7-A4D2-EFFA78CCED33}" ShowInNewForm="FALSE" Type="DateTime" Name="TimeEnd" DisplayName="TimeEnd" SourceID="http://schemas.microsoft.com/sharepoint/v3" StaticName="TimeEnd" Node="/my:RoomBooking/my:Schedule/my:TimeEnd" ></Field>
        </Fields>
    </MetaData>
</List>

Web Parts on a page can be interconnected using connection parameters to pass values between them. Similar to property promotion, InfoPath fields can be promoted as Web Part connection parameters. This allows Web Parts to send data to or get data from a field in an InfoPath form without any further coding. Especially when using the newly introduced InfoPath Form Web Part, these connection parameters enable you to quickly interconnect your form with other SharePoint Web Parts. Figure 15-21, which was already described in connection with property promotion earlier, shows this dialog that allows you to add new Web Part connection parameters.

To specify Web Part connection parameters, you can use the Property Promotion category, accessible either through the Publishing wizard or the Form Options dialog. When adding new Web Part connection parameters, you will be asked to select the field you want to promote and enter a name for the parameter. Finally, you need to choose the parameter type: input, output, or inputoutput. Input parameters can be used to retrieve data from other Web Parts. Output parameters can send data to other Web Parts. If you want to do both, you must select "inputoutput."

When your form already exists, you can use property demotion to set fields in your form. But often you want to preload information in your form when a new form is created. In this case, you can pass parameters to your browser form using request parameters. If you write your own application page that hosts the XmlFormView, you can access the form's XML data and directly write parameters into the XML. But if you don't, request parameters might be the solution for you.

You can pass your additional parameters as so-called input parameters via HTTP request parameters. There are two ways to access these parameters:

InfoPath offers access to input parameters either for InfoPath Filler forms or for browser-based forms. They are handled exactly the same way. In the load event you access the LoadingEventArgs parameter e and select the desired parameter using the [] selector:

String param = e.InputParameters["param"];

In this case, you don't have to deal with HTTP request parameters. But since your form is hosted inside a web page you can also read the HTTP request parameters from within your form template in the form code. All you need to do is add a reference to the System.Web assembly. Then you can access the QueryString collection of the HttpRequest to read all the parameters required to load data into the form. Of course, you can also access the other properties of the request (e.g., Url, Headers, UserAgent, LogonUserIdentity, and anything else that might be useful when programming your form). You can retrieve the browser session to exchange data between SharePoint and InfoPath. The next example demonstrates both ways to load data into your form using a request parameter. Instead of simply writing the value directly into the form, the parameter will be used to call a web service that is responsible for fetching the data that is required in the form.

To begin, add the following reference to your project, along with the using statement, to access the HTTP request:

using System.Web;

Now you can obtain the request parameters in your form-loading event to retrieve a parameter that identifies an item from the QueryString. With this itemid parameter, the GetItemData web service is called. The results are then stored into the form using XPathNavigator.

public void FormEvents_Loading(object sender, LoadingEventArgs e)
{
    // Get the request parameter using InputParameters:
    string itemId = e.InputParameters["itemId"];
    // Get the request parameter directly from the request:
    itemId = HttpContext.Current.Request.QueryString["itemId"];

    XPathNavigator form = MainDataSource.CreateNavigator();

    if (!String.IsNullOrEmpty(itemId))
    {
        // Set the parameter for the web service query
        DataSources["GetItemData"].CreateNavigator().SelectSingleNode(
            "/dfs:myFields/dfs:queryFields/tns:GetItemData/tns:itemId",
            NamespaceManager ).SetValue(itemId);

        // Query web service and create navigator
        DataSources["GetItemData"].QueryConnection.Execute();
        XPathNavigator itemdata = DataSources["GetItemData"].CreateNavigator();

        // Fill the Name field with the value from the web service
        XPathNavigator nodeName = form.SelectSingleNode(

"/my:ItemForm/my:Name", NamespaceManager);
        nodeName.SetValue(itemdata.SelectSingleNode(
"dfs:myFields/dfs:dataFields/tns:GetItemData/tns:GetItemDataResult/tns:ItemName",
            NamespaceManager).Value);

        // Fill the Price field with the value from the web service
        XPathNavigator nodePrice = form.SelectSingleNode(
            "/my:ItemForm/my:Price", NamespaceManager);
        nodePrice.SetValue(itemdata.SelectSingleNode(
"dfs:myFields/dfs:dataFields/tns:GetItemData/tns:GetItemDataResult/tns:ItemPrice",
            NamespaceManager).Value);
    }
}