Share via

Extending Form Libraries

  • Article

Extending Form Libraries

This topic describes ways in which a form library in Microsoft® Windows® SharePoint™ Services can be extended. Third-party developers can create a DLL that provides a launcher control for opening the XML files of a form library in an XML editor that is compatible with Windows SharePoint Services. A properties.xfp file can be created that defines functionality for a form library.

A form library list type is an extension of the Document Library base list type and is designed for XML files. A form library provides the following functionality for working with XML files:

  • Property Promotion.   Promotes data stored in the XML file as columns in the SharePoint form library.
  • Link Management.   Keeps links in the XML files associated with the template of the form library.
  • Merge Forms.   Sends multiple XML files to a client application to be merged.

Creating and registering a launcher control

Third-party developers can create a DLL that provides the launcher control for opening XML documents in an XML editor. The control must provide the same interface for creating, editing, and merging XML files, as well as for customizing templates, as described for the OpenXMLDocuments control. The control must have a ProgID, such as SharePoint.OpenXMLDocuments, and be installed and registered on the client computer.

The DOCICON.XML file for a Windows SharePoint Services deployment can be customized so that the ProgID (for example, Word.Document) and the file extension of a specific document type map to the ProgID of the launcher control and to an icon for representing documents in the form library. For information on customizing DOCICON.XML, see Adding a Document Template, File Type, and Editing Application to a Site Definition.

Property Promotion

The XML property promotion process defines how to present information from XML files in the columns of a Windows SharePoint Services form library. The columns that are to be promoted, and the data that the XML parser of a form library requires to extract information and store it in list columns, are defined in the properties.xfp file, which is stored in the Forms folder of the form library. Each field defined in the properties.xfp file creates a column in the UserData table of the database, and each XML file in the form library adds a corresponding row to the table. XML Property Promotion works in conjunction with columns already in the SharePoint form library but adds additional columns.

Using Collaborative Application Markup Language (CAML), you can create a properties.xfp file and place it in the Forms folder of a form library to customize XML Property Promotion.

File format for properties.xfp

A properties.xfp file supports the following format in CAML.

<Fields [ FormAggregation="TRUE|FALSE" ]>
  <Field
    [ ReadOnly="TRUE|FALSE" ]
    [ Hidden = "TRUE|FALSE" ]
    [ Name="Internal Name" ]
    [ DisplayName="Display Name" ]
    [ Node="..." ] or [ PITarget="PI_Target" PIAttribute="PI_Attribute" ]
    [ Aggregation="Count | Sum | ..." ]
    [ MaxLength="255" ]
    [ Required="TRUE|FALSE" ]
    [ Viewable="TRUE|FALSE" ]
    [ Type="Note | Text | Boolean | Number | DateTime | Signature | ProgId | Link" ]  (Signature, ProgId and Link will change to Text on server)
    [ Format="DateOnly" ]
    [ Sortable = "TRUE" ]
    [ ... ANY OTHER CAML FIELD ATTRIBUTES... ] />
</Fields>
Descriptions
  • Fields element. Required root node that has the following attribute and that contains repeating Field elements:
    • FormAggregation attribute. Optional Boolean. true if Merge Forms is available for the form library. The default value is false.
    • Field element. Required repeating element that defines one field that maps to a single column in the form library for property promotion. Possible attributes include the following:

      • ReadOnly attribute. Optional Boolean. true if values cannot be edited directly in the form library and then saved to the XML file. The default value is false.

      • Hidden attribute. Optional Boolean. true if the field cannot be displayed as a column in the view. The default value is false.

      • Name attribute. Optional Text. The name of the field as used in the logic of the SharePoint site, such as in object model calls, CAML, and script. This element is optional for fields of type Signature, ProgId, or Link but required for all other types.

      • DisplayName attribute. Optional Text. The title of the field.

      • Node attribute. Optional Text. The XPath expression for the node that is being promoted. The XML parser populates the value of the field with the value in the XML file at the location specified by the value of this attribute.

      • PITarget attribute. Optional Text. Used in conjunction with the PIAttribute value. PITarget specifies the name of the processing instruction (PI). The XML parser populates the value of this field with the value in the XML file in the PI specified by PITarget and PIAttribute.

      • PIAttribute attribute. Optional Text. Used for Link Management PI links, specifying the attribute in the PITarget element.

      • Type attribute. Optional Text. Specifies the field type of the field. Possible values include Note, Text, Boolean, Number, DateTime, Signature, ProgId, and Link. Signature, ProdID and Link change to Text on the server. The type is not extensible by third parties and must be one of these values in the properties.xfp file. The default value is Text.

      • Aggregation attribute. Optional Text. If the XPath expression returns the collection of values, this attribute specifies the action on the set returned. This action can be either an aggregation function or an indication of the particular element within the collection.

        Possible values include the following:

        • sum
        • count
        • average
        • min
        • max
        • merge
        • plaintext. Converts node text content into plain text.
        • first. Specifies that property promotion and demotion be applied to the first element in the collection.
        • last. Specifies that property promotion and demotion be applied to the last element in the collection.

      • MaxLength attribute. Optional Integer. Sets the maximum length of a string for the field. Longer strings are concatenated. The value of the MaxLength attribute is restricted by the quota set for the user in Windows SharePoint Services. The default value is dependent on the field type and governed by site settings.

      • Required attribute. Optional Boolean. true if the field does not accept null values. The default value is false.

      • Viewable attribute. Optional Boolean. true if the field is added to the default view. The default value is true.

      • Format attribute. Optional Text. Used to distinguish between Date and DateTime values. Must be DateOnly for type xsd:date in data.

      • Sortable attribute. Optional Boolean. true if the column can be sorted. Must be false for Note field types in Windows SharePoint Services.

The preceding format is supported for the properties.xfp file, but other attributes of the Field element may also be included.

Example

The following example shows the format of a properties.xfp file.

<Fields FormAggregation="TRUE" . . . >
  <Field Type="ProgID". . . Viewable="no"/>
  <Field Type="Link" . . . />
  <Field Type="Signature" . . . />
  <Field Type="Text" DisplayName="Issue"
      Node="/issue/title" . . . />
  <Field Type="Number" DisplayName="# of Actions"    Node="/issue/actions/action"
      Aggregation="count" . . . />
  <Field ReadOnly="TRUE" DisplayName="Status" Name="{01A…60}"
      Node="/issue/status" Viewable="yes" Type="Text"/>
      .
      .
      .
</Fields>

Note  For purposes of illustration only, ellipses have been used in place of attributes.

Link Management allows you to keep the forms in a form library synchronized with the form library template. The mechanisms for Link Management include the following:

  • Automatic link management.   Once a form is synchronized with the template, if any site, subsite, or library is renamed, the link is automatically kept synchronized with the template URL of the form library.

    Note  Link management does not occur right away. A flag is set and it occurs when the file is requested for download.

  • Manual relink.   If the form is initially out of synch with the template URL of the form library, selecting Relink forms to this form library on the Customize page allows a manual relinking. This is used for uploaded documents, or for form libraries copied from one server to another.

Both mechanisms require that the field to be relinked is specified by using Type="Link". If the field to be relinked is in the PI, use the following format in the properties.xfp file:

<Field Type="Link" PITarget="PI_Element" PIAttribute="PI_Attribute"/>

For a normal XPath expression, use the following format:

<Field Type="Link" Node="XPath"/>

Note  The Name attribute is not specified.

Merge Forms

Merge Forms provides form libraries a mechanism for processing multiple XML files at the same time. This function must be enabled in the properties.xfp file and implemented by the launcher control through a MergeDocuments2 method as described for the OpenXMLDocuments control.

Merge Forms is specified by the FormAggregation attribute of the Fields element, as follows:

<Fields FormAggregation="TRUE">
.
.
.
</Fields>

In addition to making the customizations described in this topic, a custom list definition can be created for form libraries. For more information, see Creating a List Definition.