Extending Form Libraries

This content is outdated and is no longer being maintained. It is provided as a courtesy for individuals who are still using these technologies. This page may contain URLs that were valid when originally published, but now link to sites or pages that no longer exist.

Form libraries are retained in Windows SharePoint Services 3.0 only for purposes of backward compatibility with XML-based forms editors that do not support publishing forms to content types.

In Windows SharePoint Services 3.0, 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, there is no difference in the functionality offered by each type of library.

In Windows SharePoint Services 3.0, the special form functionality is encapsulated in the Form content type, and content types derived from it, rather than 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 previous 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.

Extending Form Libraries Using an .xfp File

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.

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

Property Promotion Using an .xfp File

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 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 form library but it adds columns you specify.

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 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 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 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. 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 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 kept synchronized automatically with the template URL of the form library.

  Note

  Link management does not occur immediately. 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 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"/> 

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

See Also

Concepts

Extending Forms