Extending Form Libraries

Last modified: April 13, 2010

Applies to: SharePoint Foundation 2010

Form libraries are retained in Microsoft SharePoint Foundation only for purposes of backward compatibility with XML-based forms editors that do not support the publication of forms to content types.

In SharePoint Foundation, form libraries and document libraries differ in only one substantive way: by the default content type with which they are created. Form libraries include the Form content type as their default content type; document libraries contain the Document content type as their default content type. Other than this distinction, there is no difference in the functionality offered by each type of library.

In SharePoint Foundation, the special form functionality is encapsulated in the Form content type, and content types derived from it, rather than existing in the form library. Therefore, to use the specialized form functionality, you need add only the Form content type, or a content type derived from it, to your document library. This frees users from the restriction of having to store their forms in a separate library from documents, and only being able to store a single type of form in each form library. Now, not only can you store multiple types of forms in a single library, you can store both forms and documents in the same library.

For information about extending the Form content type and content types derived from it, including creating a launcher control, property promotion and demotion, link management, and merge views, see Extending Forms.

A form library provides the following functionality for working with XML files:

  • Property Promotion — Promotes data that is stored in the XML file as columns in the SharePoint form library.

  • Link Management — Keeps links in the XML files that are associated with the template of the form library.

  • Merge Forms — Sends multiple XML files to a client application to be merged.

You can create a Properties.xfp file that defines custom functionality for a form library.

Note Note

In SharePoint Foundation, the specialized form functionality described in this topic is included in the Form content type and content types that are derived from it. The ability to extend a form library by using an .xfp file is included in SharePoint Foundation solely for backward compatibility with XML-based forms editors that do not support publishing forms to content types. For information about extending the Form content type, see Extending Forms.

Property Promotion Using an .xfp File

The XML property promotion process defines how to present information from XML files in the columns of a SharePoint Foundation form library. The columns to promote, 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 that are already available in the SharePoint Foundation form library but it adds columns you specify.

By using Collaborative Application Markup Language (CAML), you can create a custom Properties.xfp file and place it in the Forms folder of a form library to customize XML property promotion.

CAML Format for properties.xfp

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

Syntax

<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 FormAggregation 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 Foundation 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 XML Path Language (XPath) expression for the node to promote. 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 (applies property promotion and demotion to the first element in the collection), last (applies property promotion and demotion 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 SharePoint Foundation. The default value is dependent on the field type and is 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 SharePoint Foundation.

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. For purposes of illustration only, ellipses are used in place of attributes.

<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>

Link Management by Using an .xfp File

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   After a form is synchronized with the template, if any site, subsite, or library is renamed, the link is automatically synchronized with the template URL of the form library.

    Note Note

    Link management does not occur immediately. A flag is set and then link management occurs when a 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 that are copied from one server to another.

Both automatic and manual link management require you to specify the field to relink by using Type="Link". If the field to relink 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"/> 

NoteNote

The Name attribute is not specified.

Merge Forms by Using an .xfp File

Merge Forms provides form libraries with 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>
Show: