Using Content Types to Specify XML Document Properties
Applies to: SharePoint Foundation 2010
When Microsoft SharePoint Foundation 2010 invokes the built-in XML parser to parse XML files, the parser uses the document's content type to determine which document properties map to which content type columns, and where those document properties are stored in the document. Therefore, to have SharePoint Foundation use the built-in XML parser with your XML files, you must do the following:
Create a content type that includes the necessary parsing information. For each document property you want to promote or demote, include a field definition that includes the name of the document property that maps to the column the field definition represents, and where the document property is stored in the document.
Make sure that the content type ID is a document property that is demoted into the document. This ensures that the built-in XML parser can identify and access the correct content type for the document. For more information, see Specifying Document Content Type for XML Parsing.
Content Type Information for XML Parsing
Document properties are promoted to and demoted from columns on the document library in which the document is stored. If the document is assigned a content type, these columns are specified in the content type definition. In the content type definition XML, each column included in the content type is represented by a FieldRef element.
Note
Field elements represent columns that are defined for a site or list. FieldRef elements represent references to columns that are included in the content type. The FieldRef element contains column attributes that you can override for the column as it appears in this specific content type, such as the display name of the column, and whether it is hidden or required on the content type. This information also includes the location of the document property to map to this column as it appears in the content type. This enables you to specify different locations for the document property that maps to the column in different content types.
Because of this, to specify the information the built-in XML parser needs to promote and demote a document property, you must edit the FieldRef element that represents the document property's corresponding column in the content type definition.
The following figure shows the actions the parser takes when an XML file is checked in to a document library. SharePoint Foundation invokes the parser, which looks at the content type ID column to determine the location in the document where its content type ID is stored. The parser then looks inside the document for its content type at this location. The parser examines the content type to determine which FieldRef elements contain document property information. For each FieldRef element mapped to a document property, the parser looks for the document property at the location in the document specified in the matching FieldRef element. If the parser finds the document property at the specified location, it promotes that value to the matching column.
When an XML document is first uploaded to a document library, the built-in XML parser must determine the content type of the document, and whether that content type is associated with the document library. For more information, see Specifying Document Content Type for XML Parsing.
.gif "XML property promotion")
You can edit several attributes in a Field or FieldRef element to map that element to a document property and specify the location of the property in the document.
First, the Field or FieldRef element must contain an ID attribute that specifies the ID of the column in the document library. For example:
<FieldRef
ID="{4B1BF6C6-4F39-45ac-ACD5-16FE7A214E5E}"
Name="EmployeeID”/>
Next, add additional attributes to the Field or FieldRef element that specify the location of the document property in the document. Document properties can be stored in the following locations:
The XML content of the document
The processing instructions of the document
The attributes you add to the Field or FieldRef element to specify the property location depends on whether the property is stored as XML content or processing instructions. These attributes are mutually exclusive; if you add an attribute that specifies a location in the XML content, you cannot also add attributes that specify a location in the processing instructions.
To edit a column's field definition schema programmatically, use the SPField.SchemaXML object.
Specifying Properties in Document XML Content
If you store the document property in the document as XML content, you specify an XPath expression that represents the location of the property within the document. Add a Node attribute to the Field or FieldRef element, and set it equal to the XPath expression. For example:
<FieldRef
ID="{4B1BF6C6-4F39-45ac-ACD5-16FE7A214E5E}"
Name="EmployeeID"
node="/my:myFields/my:employee"/>
Document Property Value Collections
If you specify an XPath expression that returns a collection of values, you can also include an aggregation attribute in the Field or FieldRef element. The aggregation attribute specifies the action to take on the value set that is 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.
For example:
<FieldRef
ID="{4B1BF6C6-4F39-45ac-ACD5-16FE7A214E5E}"
Name="TotalToExpense”
node="/my:myFields/my:expense"
aggregation="sum"/>
Specifying Properties in Document Processing Instructions
Because processing instructions can contain data other than just XML, XPath expressions are insufficient to identify document properties stored in processing instructions. Instead, you must add a pair of attributes to the Field or FieldRef element that specify the processing instruction and processing instruction attribute you want to use as a document property:
Add a PITarget attribute to specify the processing instruction in which the document property is stored in the document.
Add a PIAttribute attribute to specify the attribute to use as the document property.
For example:
<FieldRef
ID="{4B1BF6C6-4F39-45ac-ACD5-16FE7A214E5E}"
Name="columnName"
PITarget="mydocumenttype"
PIAttribute="propertyAttribute"/>
These attributes instruct the parser to examine the following processing instruction and attribute for the document property value:
<?mydocumenttype propertyAttribute="value"?>
You can also add another pair of attributes, PrimaryPITarget and PrimaryPIAttribute. This attribute pair is optional. Like PITarget and PIAttribute, they work in unison to identify the location of the document property. However, if they are present, the built-in XML parser looks for the document property in the location they specify first. If there is a value at that location, the parser uses it and ignores the PITarget and PIAttribute attributes. The parser looks for the document property at the location specified by the PITarget and PIAttribute attribute pair only if the location specified by the PrimaryPITarget and PrimaryPIAttribute attributes returns a null value.
If you specify the PrimaryPITarget and PrimaryPIAttribute attributes, you must also specify PITarget and PIAttribute attributes. The parser uses the PrimaryPITarget and PrimaryPIAttribute attributes only if the processing instruction attribute specified by the PITarget and PIAttribute pair does not exist in the document, not if that attribute exists but is null or empty.
See Also
Concepts
XML Document Property Promotion and Demotion