Forms Libraries and Microsoft Office InfoPath

Since Microsoft Windows SharePoint Services 2.0, WSS has provided integration with Office InfoPath through forms libraries. A forms library is a specialized type of document library designed to store XML documents created from InfoPath forms. The main difference is that standard document libraries are based on a built-in WSS content type named Document, whereas forms libraries are based on a built-in content type named Form that inherits from Document.

InfoPath and WSS provide a good deal of synergy when used together because users can employ InfoPath to produce XML documents that are then stored in WSS forms libraries. When stored in WSS, these XML documents are afforded all of the benefits of standard document libraries, such as metadata columns, versioning, check-in/checkout, event handlers, and workflows. The fact that InfoPath documents are stored as schema-validated XML documents makes their content very easy to access programmatically.

Although it is not the intention of this book to teach you how to design forms with InfoPath, we do want to provide a quick look at provisioning a forms library and configuring it with a custom InfoPath form template. An InfoPath form template is saved as a CAB file with an .xsn extension. Inside the form template is an .xsd file that defines the XML schema associated with the form template and with all XML documents created from the form template. The DocumentManager sample contains an InfoPath form template named Leadsheet.xsn that provides users with the input form, as shown in Figure 7-5.

Figure 7-5: A WSS forms library with a custom form template can serve up InfoPath forms.

As you can see from Figure 7-5, the Leadsheet form is used to track sales leads gathered at industry events, such as conferences and trade shows. Each Leadsheet form is designed to track information about a specific event, including its location and date. The Leadsheet form also makes it possible to track many different sales leads. Note that the XML schema behind the Leadsheet form requires at least one sales lead but allows the user to enter as many sales leads as needed.

The DocumentManager feature provisions an instance of a forms library and configures it to use Leadsheet.xsn as its document template by using the same technique shown earlier in this chapter with the Proposals document library. The DocumentManager features contains a ListInstance element to provision the forms library instance as well as a Module element to provision an instance of Leadsheet.xsn into the site so that it can be used as the document template.

 <ListInstance  FeatureId=""  TemplateType="115"    Description="Leadsheets for tracking sales leads"  OnQuickLaunch="True"  Title="Leadsheets"  Url="Leadsheets" > </ListInstance> <Module Name="LeadsheetTemplate" List="115" Url="Leadsheets/Forms">   <File Url="Leadsheet.xsn" Type="GhostableInLibrary" /> </Module>

The FeatureId and TemplateType are different than those shown earlier because the forms library type is defined with a type ID of 115 inside another feature named XmlDocument. However, all other aspects of provisioning the forms library instance are the same, including the code in the FeatureActivated event for configuring the document template and other properties of the new forms library. Because a forms library is a specialized type of document library, you can program against it in the FeatureActivated event by using the SPDocumentLibrary class.

 SPWeb site = (SPWeb)properties.Feature.Parent; SPDocumentLibrary libLeadsheets; libLeadsheets = (SPDocumentLibrary)site.Lists["Leadsheets"]; libLeadsheets.DocumentTemplateUrl = @"Leadsheets/Forms/Leadsheet.xsn"; libLeadsheets.EnableVersioning = true; libLeadsheets.EnableFolderCreation = false; libLeadsheets.ForceCheckout = true; libLeadsheets.Update();

You’ve now seen how to provision the Leadsheets forms library and configure some of its properties. Next, we will bind an event handler to the ItemAdded event that fires whenever a user uploads a new Leadsheet document. This gives us an opportunity to see how to access the content of a document from an event handler that is bound to a document library.

You can bind an event handler to a document library by using a Receivers element in a feature or by using the WSS object model, as demonstrated in Chapter 6. Using a Receivers element in a feature isn’t very flexible because you can bind an event handler only by using a list type ID such as 101, which binds the event handler to all standard document libraries, or 115, which binds the event handler to all forms libraries. However, in our case, we simply want to bind an event handler to a single instance of the forms library type, which can be accomplished by calling the Add method on the EventReceivers collection.

 string asmName = "DocumentManager, [full 4-part name]"; string className = "DocumentManager.ItemEventHandler"; libLeadsheets.EventReceivers.Add(SPEventReceiverType.ItemAdded,                                  asmName, className);

Now that you have seen the code to bind the event handler, let’s look at the event handler itself. Just like the event handler for a standard list type, an event handler for a document library is created by using a class that inherits from SPItemEventReceiver. In the following example, we are simply going to handle the ItemAdded event that fires asynchronously after a new InfoPath form is added to the Leadsheets Forms library. The basic structure of the event handler class looks like the following:

 namespace DocumentManager {   public class ItemEventHandler : SPItemEventReceiver {     public override void ItemAdded(SPItemEventProperties properties) {       SPFile documentFile = properties.ListItem.File;       using (Stream documentStream = documentFile.OpenBinaryStream()) {         // program against document stream       }     }   } }

As you can see, the SPItemEventProperties parameter of the ItemAdded method makes it easy to access the SPFile object associated with the InfoPath form that has just been uploaded. Once you have a reference to this SPFile object, you can access the form’s content as a byte array by calling the OpenBinary method or as a stream by calling the OpenBinaryStream method. You should observe that the preceding example uses the best practice of opening the stream within a using statement so that the stream object is properly disposed of after it is used.

Once you open a stream to access the InfoPath form’s content, you have several options. For example, you can read the XML content inside the form by using a class from the System.Xml namespace, such as XmlReader or XmlDocument. However, there’s an easier method. Because every InfoPath form has an associated XML schema, you can use the XSD.EXE utility to generate a schema-derived class, which is the technique used by the DocumentManager solution.

The DocumentManager project contains a source file named Leadsheet.cs that is generated with XSD.EXE from the XML schema associated with the InfoPath form Leadsheet.xsn. Inside Leadsheet.cs are two schema-generated classes named Leadsheet and Lead. You can use the XmlSerializer class to deserialize the XML content in the InfoPath form into strongly typed objects. For example, you can write the code inside the ItemAdded event handler to deserialize the content of the form into a Leadsheet object. You can then access the leads by using a foreach loop to enumerate through Lead objects.

 XmlSerializer serializer = new XmlSerializer(typeof(LeadSheet)); SPFile docFile = properties.ListItem.File; using (Stream documentStream = docFile.OpenBinaryStream()) {   LeadSheet leadsheet = (LeadSheet)serializer.Deserialize(documentStream);   foreach (Lead lead in leadsheet.Lead) {     string leadName = lead.Name;     string phone = lead.Phone;     string email = lead.Email;   } }

The DocumentManager demonstrates this technique by deserializing the Leadsheet data and writing information about each of the leads into a WSS list in the current site named Sales Leads. Each time that a new InfoPath form is uploaded, this event handler automates the task of taking the data inside it and writing it into a list. The following code is a complete listing of the ItemAdded event handler from the DocumentManager solution.

 public override void ItemAdded(SPItemEventProperties properties) {   XmlSerializer serializer = new XmlSerializer(typeof(LeadSheet));   SPWeb site = properties.OpenWeb();   SPList targetList = site.Lists["Sales Leads"];   SPFile docFile = properties.ListItem.File;   using (Stream documentStream = docFile.OpenBinaryStream()) {     LeadSheet sheet = (LeadSheet)serializer.Deserialize(documentStream);     foreach (Lead lead in sheet.Lead) {       SPListItem newItem = targetList.Items.Add();       newItem["Lead Name"] = lead.Name;       newItem["Phone"] = lead.Phone;       newItem["Email"] = lead.Email;       newItem.Update();     }   } }

It’s important to note that after-the-fact events, such as ItemAdded, fire asynchronously, which means that the event handler might continue to run even after control is returned back to the user. Asynchronous event handlers run under the identity of the user that triggers them. For example, imagine that the user Brian Cox uploads a new InfoPath form that causes this event handler to run. When the ItemAdded event handler adds new items to the Sales Leads list, it does so with Brian’s permissions and with Brian’s identity. We will discuss how you can change this default behavior of an event handler when we discuss security in Chapter 10, “Application Security.”

Tip 

If you are using only WSS and not Microsoft Office SharePoint Server (MOSS), the use of InfoPath forms requires the installation of Microsoft InfoPath on the desktop of each user who requires access to these forms. However, MOSS provides new technology involving server-side components that can render InfoPath forms within a browser, thus eliminating a user’s dependency on InfoPath as well as eliminating dependencies on the Microsoft Internet Explorer Web browser and the Microsoft Windows operating system. This technology is included with Office Forms Services, which is part of the MOSS Enterprise Edition and also in a standalone product named Office Forms Server.