Thursday 6 February 2014

InfoPath

InfoPath is a great way to easily gather and present XML data to the masses. But what about efficiently presenting a massive amount data? Tons of data (e.g., a list of hundreds product names) usually find their ways into lists that we’ll find on SharePoint, in a database, or just sitting in an XML file. Controls like Repeating Sections and Tables are useful mechanisms for displaying lists of data. But their usefulness is limited to how efficiently the user of your form can find and work with such large lists of data. An easy solution to effectively present large lists of data to your users is through sorting that data.
No Sorting Options in InfoPath
Try scouring the Repeating Table or Repeating Section controls’ properties dialogs for anything related to “sort”. Sorry to say, you’ll come up empty handed. That’s why we thought you’d find this blog entry handy. Our goal is to show you how to sort any repeating data and to do so in many different ways: sort by string, sort by number, sort ascending or descending, and even sort by different fields (or columns) in the repeating data. What we’ll show you, in both the code and the design of the view, is designed to be browser-compatible. This means you can publish this form template to a SharePoint server running Forms Services 2007 and fill out the form in a Web browser. Let’s get started.
 
Figure 1: Filling out the SortingPeople sample form template
The sample form template is attached; download the ZIP to your desktop, expand it, then right-click the XSN and select "Open in Design Mode". This sample requires InfoPath 2007, and will work in the browser when published to InfoPath Forms Services.
The View for the SortingPeople Form TemplateTo show you how to sort data in your form, we’ll use a concocted example to sort a list of people. As you can see in Figure 1, there are various options to sort the data. Clicking the “Sort” Button triggers the sort otherwise the data is not sorted automatically (more on this later). You can also sort by clicking any of the “Sort by this column” Buttons in the header and footer of any column. There are three columns in the Repeating Table representing our repeating data: Last Name, First Name, and Age. (The string data type is used for the first two columns and an integer data type for the last column.) In Figure 1, we’ve filled out the form with names of famous architects. (Their ages are fictitious.) While we’re not working with enough data to really justify a sort, this example is simply for demonstrative purposes. As you might expect, we can sort the Repeating Table data by any column and by any direction (ascending or descending). At any time we can change the existing data or even add or remove rows. But we would need to invoke the sorting functionality to put things into place again.
The Data Source for the SortingPeople Form Template
To begin designing this form template we started with controls and the data source. We inserted a Repeating Table control and renamed its data source groups and fields to map with our people example. The main data source is shown in Figure 2. To accommodate the various sorting options that we expose via controls at the top of the view (e.g., the Sort By Drop-Down List Box), we’ve added attribute fields under the SortingPeople document element. These attribute fields remember, for example, whether we’re sorting by the Last Name or the Age column.
Figure 2: Data source for the SortingPeople sample form template
Considerations When Sorting DataNow we’ll look at how we implemented sorting functionality behind this form template. This is accomplished through C# code behind the form. While we could have opted for an easier XSL-based implementation to sorting data, it would not have been compatible with Forms Services. So we’re left to actually sorting the data. There are advantages as well as disadvantages to our approach. Sorting the data is preferred when you want to persist the sorting in the saved or submitted form. While the initial cost is much higher to sort the data in the data source instead of the view, there is much less processing that occurs on subsequent visits to that data because it will already be sorted. If your form template has multiple views, switching to and from a view that performs an XSL sort is very expensive. On the contrary, a sorted data source adds no additional processing requirements on view switches. A final reason why you may want to sort the data in the data source instead of the view: submitting sorted data to a database or Web service may be optimal (or even a requirement) for that backend system.
Sorting Data with C# Form CodeTo best understand how we designed the code behind form template to support sorting, we’ll be talking about its C# form code and how it interacts with the main data source. Let’s start by looking at some of the supporting form code that will make it easier for us to implement the sort feature. The properties are used within the sort itself to read the options at the top of the view about how to sort the data. The methods are very useful helpers that we use throughout our sample code.
/// <summary>
/// Returns the "Sort By" Drop-Down value.
/// The value returned by this property MUST match with an item within the Repeating Table.
/// </summary>
private string SortBySelection
{
    get { return GetValue("@my:SortBy").Replace(" ",string.Empty); }
}

/// <summary>
/// Does the user want the SortBy by number (true) or string (false)?
/// </summary>
private bool SortAsNumber
{
    get
    {
        return 0 == GetValue("@my:SortAs").CompareTo("number");
    }
}

/// <summary>
/// Does the user want an ascending (asc) or descending (des) sort?
/// </summary>
private bool SortAscending
{
    get
    {
        return 0 == GetValue("@my:Order").CompareTo("asc");
    }
}

/// <summary>
/// Helper to wrap an int within brackets.
/// </summary>
/// <param name="intToWrap"></param>
/// <returns></returns>
private string WrapAsIndexer(int intToWrap)
return WrapAsIndexer(intToWrap.ToString()); }

/// <summary>
/// Helper to wrap a string within brackets.
/// </summary>
/// <param name="strToWrap"></param>
/// <returns></returns>
private string WrapAsIndexer(string strToWrap)
return "[" + strToWrap + "]"; }

/// <summary>
/// Helper to get an XPathNavigator's value.
/// </summary>
/// <param name="xpath"></param>
/// <returns></returns>
private string GetValue(string xpath)
{
    return Root.SelectSingleNode(xpath, NamespaceManager).Value;
}

/// <summary>
/// Helper to set an XPathNavigator's value.
/// </summary>
/// <param name="xpath"></param>
/// <param name="value"></param>
private void SetValue(string xpath, string value)
{
    Root.SelectSingleNode(xpath, NamespaceManager).SetValue(value);
}

/// <summary>
/// Helper to get the document element of the main data source.
/// </summary>
private XPathNavigator Root
{
    get { returnCreateNavigator().SelectSingleNode("/my:SortingPeople", NamespaceManager); }
}
Next, let’s take a look at the code behind all of the Buttons in our form template. We created these event handlers through each Button’s properties dialog. Their implementations are quite trivial. You can see that adding additional sorting columns to the Repeating Table is a simple task. If you wanted to add a column that doesn’t need to be sorted, there’s nothing to do beyond adding the column in the Table!
public void SortButton_Clicked(object sender, ClickedEventArgs e)
{     
    SortList();
}

public void LastNameSort_Clicked(object sender, ClickedEventArgse)
{
    SetValue("@my:SortBy""Last Name");
    SortList();
}

public void FirstNameSort_Clicked(object sender, ClickedEventArgse)
{
    SetValue("@my:SortBy""First Name");
    SortList();
}

public void AgeSort_Clicked(object sender, ClickedEventArgs e)
{
    SetValue("@my:SortBy""Age");
    SortList();
}
Now the million dollar question: what’s behind the SortList method? Let’s look and then we’ll explain how it works.
/// <summary>
/// Bubble sorts the list of people.
/// </summary>
private void SortList()
{
    string sortBy = SortBySelection;
    string itemsToSort = "my:People/my:Person";
    System.Globalization.CultureInfo currentThreadCulture =
        System.Threading.Thread.CurrentThread.CurrentCulture;

    int numPeople = Root.Select(itemsToSort, NamespaceManager).Count;

    // basic bubble sort implementation
    for (int i = 1; i < numPeople; i++) // xpath is 1-based
    {
        for (int j = i + 1; j <= numPeople; j++) // keep j ahead of i; we can index [numPeople]
        {
            // swap (i,j) if necessary
            string iValue = GetValue(itemsToSort + WrapAsIndexer(i) + "/my:" + sortBy);
            string jValue = GetValue(itemsToSort + WrapAsIndexer(j) + "/my:" + sortBy);

            // Do we sort by number or string?
            if (SortAsNumber)
            {
                int iNum, jNum;
                if (!Int32.TryParse(iValue, out iNum) || !Int32.TryParse(jValue, out jNum))
                {
                    // Let InfoPath take care of the invalid datatype with its own validation, we'll keep sorting the rest
                    continue;
                }

                if ((SortAscending && iNum > jNum) || (!SortAscending && iNum < jNum))
                {
                    Swap(itemsToSort + WrapAsIndexer(i), itemsToSort + WrapAsIndexer(j));
                }
            }
            else // SortAsString
            {
                if ((SortAscending && String.Compare(
                    iValue, jValue, true /*ignoreCase*/, currentThreadCulture) > 0)
                    || (!SortAscending && String.Compare(
                    iValue, jValue, true /*ignoreCase*/, currentThreadCulture) < 0))
                {
                    Swap(itemsToSort + WrapAsIndexer(i), itemsToSort + WrapAsIndexer(j));
                }
            }
        } // end inner-for
    } // end outer-for
}
Analyzing the C# Form Code
Let’s break down what we’re doing in this SortList method. First we get the column to use for sorting, the XPath to the repeating group that we want to sort, and the culture of the thread so we respect the current locale when sorting. Next we get the number of people that we’ll be sorting. We need this number because we’ll use it for our bubble sort implementation.
The two nested for-loops implement the bubble sort algorithm. We chose bubble sort because of its simplicity and for demonstrative purposes. (We’d recommend you use the most efficient sorting algorithm based on your requirements.) The variables i and j iterate through the people. We use the iValue and jValue variables to select the data pointed at by i and j to determine if a swap is necessary as part of the sort loop.
Next, we have an if-else statement that checks if the sort is by string or by number. A sort by number will attempt to parse out 32-bit integer values from the iValue and jValue fields. If the parse fails for any reason, we skip this specific comparison and continue trying to sort the rest of the data. Once we have integers, we do a simple comparison and swap if needed. If we’re sorting by string instead of numerical value, we use the static .NET library String.Compare method to make a culture sensitive comparison. A swap is performed if it’s necessary. (Note that we could have combined some code in the SortList method to make it more compact. We left the structure of the code unoptimized for maximum readability.)
The last bit of code we have not yet revealed is the Swap method. This method, as its name suggests, simply swaps the positions of two XPathNavigator objects as identified by their XPaths. (An XPathNavigator is a pointer into an XML tree of data. You can read more about the XPathNavigtor class on MSDN.)
/// <summary>
/// Swaps two XPathNavigators at xpath1 and xpath2.
/// </summary>
/// <param name="xpath1">First XPath.</param>
/// <param name="xpath2">Second XPath.</param>
private void Swap(string xpath1, string xpath2)
{
        XPathNavigator item1 = Root.SelectSingleNode(xpath1, NamespaceManager);
        XPathNavigator item2 = Root.SelectSingleNode(xpath2, NamespaceManager);

        // Make a copy of item1
        XPathNavigator item1Clone = item1.Clone();
        // Move item2 to item1
        item1.ReplaceSelf(item2);
        // Make the original item2 be item1 that we cloned earlier
        item2.ReplaceSelf(item1Clone);
}
Sorting Automatically
One of the things you might ask is why we decided against sorting the data automatically. The most important reason is user experience and then followed by form responsiveness. Think about what would happen if the Repeating Table rows sorted themselves whenever data changed that required a sort. Say you were entering data into a new row. You start by typing a person’s last name and then either hit tab or click into the First Name field. If the form is sorting by the Last Name field, the row may have jumped to another location relative to the other rows in the Repeating Table! You would expect that you could fill in all of the data for a new row before it sorts itself. There are also other weird cases that automatic sorting would spoil. For example, you would not see a new row added within the middle of the Repeating Table. Why? As soon as you added it, it immediately jumped to the top (or bottom) of the Repeating Table as sorted data. Let’s consider for a moment why we didn’t automatically sort because of form responsiveness; for now let’s assume that we somehow worked out all of the kinks with the user model. Obviously the form will be less responsive in InfoPath, especially on a slow computer, with so much sorting. But the real problem is realized when filling out such an intense form template in a Web browser. Every time code runs while a form is filled out in a browser, the form data is posted back to the server for processing. Postbacks themselves can take several seconds or even minutes depending on many variables including the network connection speed as well as the client and server machines’ performance capabilities. As you can see, an automatically sorting form isn’t necessarily a better form.


------------------------------
magine a scenario where the accounting department at Contoso, Inc. tracks corporate assets through an Asset Management System built on SharePoint. One module in the system allows employees to order office equipment such as laptops, conference phones, and ergonomic chairs through an InfoPath form. At first, the order form was built using only declarative logic. It could enforce required fields, surface validation messages, and submit the form to SharePoint without any code.
As the ordering process grew more complex, users started adding additional requirements to the system. The variety of inventory available to employees increased, so they wanted a way sort items by name and description real-time in the order form. Contoso also started shipping their office equipment out of three warehouses. This prevented the warehouse crew from fulfilling complete orders, and as such, the system needed to track shipping status and quantity of individual items in the order. To meet the new requirements, Contoso added the following features to the form:
  • A custom sort interface
  • Logic for managing complex data when the form is submitted
  • Logic to add items to a SharePoint list
Sort interfaces, sophisticated submit routines, and database (i.e. list) management are common requirements for forms. Fortunately, this functionality can be added to InfoPath forms with a few lines of code. Let me explain these features, the code required to build them, and the prerequisites for developing managed code in InfoPath in more detail.

Equipment Request Form

The employee orders module in the Asset Management system consists of three core components:
  1. A SharePoint form library, “Equipment Orders”, where users go to fill out the Equipment Order Request form shown below.
  2. A SharePoint list, “Equipment Inventory”, which stores the items available for users to order. This list contains fields specifying items’ names, descriptions, and quantities used to populate the Equipment Order Request form.
  3. A SharePoint list, “Equipment Shipping”, which stores a list of items ordered by users that have been scheduled for shipping. This list contains fields for the names and quantities of items being ordered as well as the name of the user who placed the order.
The Equipment Request Form enables users to sort through Contoso’s available inventory and submit a request to the warehouse for shipping.
Equipment Order Request Form
The order form is a repeating table, where each row in the table represents the name, description, and quantity of the item being ordered.
Equipment Order Request Form 

Sorting data in the form

The Equipment Order Form has a Picture Button Control displaying an arrow next to each of the column labels.
Equipment Order Request Form
The buttons are used to sort the order items in ascending order by the respective column. When the user clicks the button, the values in the selected column are compared, and the rows of data are sorted based on the comparison result.
The sorting routine in this example is based on a complete solution provided by Hagen Green. Read through his post to learn how to provide a descending sort which also takes localization and data types into consideration.
private string GetValue(string xpath)
{
  // return the value of the specified node
  XPathNavigator myNav = this.MainDataSource.CreateNavigator().SelectSingleNode(xpath, NamespaceManager);
  if (myNav != null)
    return myNav.Value;
  else
    return "";
}
private void Swap(string xpath1, string xpath2)
{
  // swap two rows of the table 
  XPathNavigator item1 = this.MainDataSource.CreateNavigator().SelectSingleNode(xpath1, NamespaceManager);
  XPathNavigator item2 = this.MainDataSource.CreateNavigator().SelectSingleNode(xpath2, NamespaceManager);

  if (item1 != null && item2 != null)
  {
    // Make a copy of item1
    // Move item2 to item1
    // Make the original item2 be item1 that we cloned earlier
                
    XPathNavigator item1Clone = item1.Clone();
    item1.ReplaceSelf(item2);
    item2.ReplaceSelf(item1Clone);
  }
}

private void SortOrder(string sortBy)
{
  string itemsToSort = "/my:myFields/my:Order/my:OrderItem";
  XPathNodeIterator items = this.MainDataSource.CreateNavigator().Select(itemsToSort, NamespaceManager);
  if (items != null)
  {
    int numItems = items.Count;
    // basic bubble sort implementation
    for (int i = 1; i < numItems; i++) // xpath is 1-based
    {
      for (int j = i + 1; j <= numItems; j++)
      {
        // swap (i,j) if necessary
        string iValue = GetValue(itemsToSort + "[" + i + "]" + sortBy);
        string jValue = GetValue(itemsToSort + "[" + j + "]" + sortBy);
        if (String.Compare(iValue, jValue, true) > 0)                       
          Swap(itemsToSort + "[" + i + "]", itemsToSort + "[" + j + "]");
                        
      }
    }
  }
}

public void ItemNameSort_Clicked(object sender, ClickedEventArgs e)
{
  // Sort order by ItemName
  // Repeat this code for the other buttons

  string sortBy = "/my:ItemName";
  SortOrder(sortBy);
}

Managing complex data during submit and updating SharePoint lists using the SharePoint object model

The user is eventually going to finish selecting items and submit the order. Each item ordered through the form is handled independently because, for example, an item in the order may be delayed or shipped from a remote warehouse. So, we need submit logic which will break up the complex data (i.e. the repeating table of items being ordered) into individual rows, and add a shipping request to the Equipment Shipping list for each item-quantity pair. After an item is added to the Equipment Shipping list, a SharePoint workflow is used to track status and manage the Inventory Equipment list’s quantity values.
  1. The first thing you’ll need to do is use the Submit Options button on the Data tab in the ribbon to add a custom submit handler to your VSTA project.
    Submit Options
  2. Add a reference to Microsoft.SharePoint.dll to your VSTA project. This will allow you to develop code using the SharePoint object model. This DLL is installed in %CommonProgramFiles%\Microsoft Shared\Web Server Extensions\14\ISAPI with your licensed copy of Microsoft SharePoint Server.
  3. Add custom submit logic to create a SharePoint list item for each item in the order form. See the code below for an example, and notice the use of the ServerInfo class. The ServerInfo class is new to InfoPath 2010 and allows you to write portable code with relative references to SharePoint server URLs.

public void FormEvents_Submit(object sender, SubmitEventArgs e)
{
  // Loop through each item-quantity pair in the order form.
  // Submit pairs to the Equipment Shipping list.
  // Note: Workflow will handle updating item quantities and track shipping status.
  using (SPSite mySite = new SPSite(ServerInfo.SharePointSiteUrl.ToString()))
  {
    using (SPWeb myWeb = mySite.OpenWeb())
    {
      XPathNodeIterator orderItems;
      if (myWeb != null && myWeb.Lists["Equipment Shipping"] != null)
      {
        SPList shippingList = myWeb.Lists["Equipment Shipping"];
        myWeb.AllowUnsafeUpdates = true;
        orderItems = this.MainDataSource.CreateNavigator().Select("/my:myFields/my:Order/my:OrderItem", NamespaceManager);
        if (orderItems != null)
        {
          while (orderItems.MoveNext())
          {
            // Add rows from the form where user selected an item and specified a quantity.
            string itemName = orderItems.Current.SelectSingleNode("./my:ItemName", NamespaceManager).Value;
            string itemQuantity = orderItems.Current.SelectSingleNode("./my:ItemQuantity", NamespaceManager).Value;
            if (itemName != string.Empty && itemQuantity != string.Empty)
            {
              SPListItem shipItem = shippingList.AddItem();
              shipItem["Title"] = itemName;
              shipItem["Quantity"] = itemQuantity;
              shipItem.Update();
            }
          }
        }
      //cleanup
      //signal successful submit
      //return
      myWeb.AllowUnsafeUpdates = false;
      e.CancelableArgs.Cancel = false;
      return;
      }
    }
  }
}

Along with the features covered above, you’ll find that code is useful for implementing complex data validation logic and managing content from multiple data sources. Such requirements are especially common when your forms are part of an advanced application. You can learn more about validation and working with the InfoPath DOM in our MSDN XmlEvent.Validating documentation and our post on working with InfoPath data sources programmatically. You can also review the InfoPath and SharePoint object models on MSDN for a more granular view into programming with InfoPath 2010.
If you’d like to get started with programming in InfoPath, then please read on. The rest of this post introduces our system requirements, integrated development environment, and programmability user experience.

How to add code to an InfoPath form

To add code to an InfoPath form:
  1. Make sure you meet the minimum system requirements.
  2. Install Visual Studio Tools for Applications (VSTA).
  3. Choose a programming language.
  4. Add event handlers and code.

Minimum system requirements

The minimum system requirement to get started with InfoPath 2010 development is Microsoft .NET Framework 2.0, but we suggest you install Microsoft .NET Framework 3.5 SP1 if you’re developing for the SharePoint platform. You can install all versions of Microsoft .NET Framework from http://www.microsoft.com/downloads.

Installing Visual Studio Tools for Applications

Visual Studio Tools for Applications (VSTA) is an optional installation component available in Microsoft Office 2010 setup. To install VSTA:
  1. Launch Office 2010 setup from your Office 2010 installation media or from the Control Panel Programs and Features application.
  2. If you’re installing a new copy of Office 2010, click the Customize button in the installer. If you’ve already installed Office 2010, choose the Add or Remove Features radio button in the installer.
  3. Set the Visual Studio Tools for Applications option to Run from My Computer and continue through the setup wizard.
Office Setup

Choosing a programming language

InfoPath 2010 allows you to program in C# and Visual Basic .NET. If you want to program with Visual Basic, you do not need to do anything to select your programming language when designing InfoPath 2010 compatible forms. If you plan on programming with C#, or adding code to InfoPath 2007/2003 compatible forms, you can change the programming language by clicking the Language button in the Code group of the Developer tab.
Developer Tab
After you click the Language button, you can change your programming language by using the Form template code language drop down:
Form Options
Hint: You can change the default language for InfoPath 2010 compatible forms by using the Options menu in the Backstage.
  1. Click the File > Options tab
  2. Click the More Options button in the General category of the InfoPath Options dialog
  3. Change the Programming language dropdowns in the Programming Defaults section of the Design Options
Options

Adding event handlers

The Developer tab is the primary entry point for programming in InfoPath 2010. It’s designed to help you add event handlers compatible with the controls and mode of the form you are designing. For example, if you don’t have a control selected on your form view, then you’ll only be able to select the events that apply to the entire form. Notice that the Loading and View Switched event below are enabled, but the entire Control Events group is disabled.
Developer Tab
But, as soon as I select a text box on the form, the Control Events group lights up.
Developer Tab
Notice that the Sign, Context Changed, and Changing events are disabled in both screenshots of the Developer tab. That’s because I’m working with a browser compatible form, and those events are only available for InfoPath Filler forms.
Note: You’ll find a table of all events, and their compatibility, towards the end of this section.
Certain control and form programming events can be accessed through buttons on other tabs in the ribbon. If you add a Picture Button control on the form view, highlight the button, and then click on the Properties tab then you’ll find the Custom Code button enabled. Clicking the Custom Code button in the ribbon will add an OnClick event for the Picture Button control.
Custom Code Button
In the Equipment Order Request form, we added a Submit event handler to add items to a SharePoint list. To do this, navigate to the Data tab, and click the Submit Options button in the Submit Form group.
Submit Options Button
This will launch the Submit Options dialog where you can check “Allow users to submit this form”, “Perform custom action using Code”, and then click the Edit Code button.
Submit Options
The Fields task pane is another main entry point to add event handlers. In the next screenshot, I access the Validating and Changed events for ItemDescription by right clicking the field in the Fields task pane and scrolling through its context menu.
Fields Taskpane
The following tables provide a list of all events and compatibility in InfoPath 2010. Note that InfoPath forms trigger three types of events: Form Events, Data Events, and Button Events. Aside from the button event, InfoPath event handling is different from other web programming paradigms (e.g. WinForm and HTML forms); events are fired when the data changes, not when control state changes. As such, you should consider the optimal configuration for your forms’ post-back settings to provide the best performance while still ensuring that events get fired when necessary. See ourperformance post on MSDN to learn more about general performance and event handler post-backs.
Tables
After you’ve designed your form and authored the source code, the final step is to publish the form. Your InfoPath form with code can be published to SharePoint and to client machines, but you need to make a security decision before you publish: configure the form as domain trust or full trust.

Domain trust forms can be published to SharePoint as Sandboxed Solutions directly from the InfoPath 2010 Designer. With Sandboxed Solutions, SharePoint Server farm administrators can restrict the resources available to the code and developers cannot access resources subject to operating system security. This establishes a safe environment where Site Collection administrators can publish code to SharePoint without the overhead of administrator approval! 
Note: Publishing full trust forms to a client-side environment requires that the form is signed with a code-signing certificate or installed through a custom MSI built in Visual Studio. Publishing a full trust form to SharePoint requires a farm administrator to activate the solution through the SharePoint Central Administration portal.
Best Practice: You should always use the lowest level of trust possible when publishing forms.

Summary

Most forms you design with InfoPath 2010 are not going to require code, but when they do, just install Visual Studio Tools for Applications and you’re ready to start programming. To add code, select the language of your choice, and use entry points in the Ribbon and Fields task pane to automatically insert event handlers. Finally, decide whether or not your form requires full-trust, and publish it to SharePoint or a client environment accordingly. 

No comments:

Post a Comment