This section describes custom properties and includes formatting and code examples for custom property statements and CAML queries within a Content By Query Web Part. First, we introduce formatting, base field information, and tips for using the CommonViewFields property. Next, we present a complete CAML query and then walk through the QueryOverride, ListsOverride, WebsOverride, and ViewFieldsOverride properties that it sets. You can add each of the property values presented in the CAML query to its respective <property value> statement in the .webpart file. Finally, we present the DataColumnRenames property and the filter, grouping, and sorting options properties.
CommonViewFields Property
You can use two formats when customizing the CommonViewFields property. You can specify fields by their internal name, or by a combination of internal name and field name, as follows:
The notation used for special characters distinguishes the internal name from the name used in the UI. For example, a space between words is represented by _x0020_ in the internal name. You can see the internal name by viewing the query string parameter in a Site Column page, or by viewing the Web Part code after you create the field. You can view the Web Part code by setting the Web Part to filter on a field, by exporting the Web Part, and then by viewing the filter properties.
.gif) Note |
|---|
For a list of additional field types that the CommonViewField property can request, see the SPFieldType enumeration in the SharePoint Foundation 2010 SDK. SharePoint Server 2010 includes four additional fields—HTML, Image, Link, and SummaryLink—that you can request. The constants that this topic lists identify the types of data that a CommonViewFields property can include. |
You can also combine CommonViewFields definitions into compound statements, which is useful to set more than one field in a property statement. Use a semicolon to separate the fields when combining definitions in one statement. For example:
Internal name of field; Internal name of field, field type
CommonViewFields is an additive property, which means that you can add a common view field on top of base fields that the Content By Query Web Part always requests. The base fields request default columns by GUID, and in the UI they appear as the Site Column names. Table 3 lists the base field names and types.
Table 3. Base field names and types
Name | Type |
|---|
Title | Text |
FileRef | Lookup |
ID | Counter |
Modified | DateTime |
Author | "User" |
Editor | User |
Created | DateTime |
PublishingRollupImage | Image |
Level | "Number" |
Note | "Note" |
In the following example, the CommonViewFields property sets the GUID, which SharePoint Server 2010 uses internally to reference the internal name of the field, the field type, the internal name of the CommonViewField, and its base type, followed by the GUID of the base type.
<property name="CommonViewFields" type="string">_Level,Number;PublishingRollupImage;</property>
QueryOverride, ListsOverride, WebsOverride, and ViewFieldsOverride Properties
Each override property—QueryOverride, ListsOverride, WebsOverride, and ViewFieldsOverride—overrides a default Content By Query Web Part behavior. To override a behavior, construct a CAML query that defines the conditions you want to set.
In the following example, we demonstrate setting custom properties for the Content By Query Web Part by using a CAML query. The CAML query does the following:
Retrieves a Created field
Sets the query to retrieve items updated in the past seven days and sorts them in descending order
Specifies the list type to query from
Retrieves data recursively from the specified Web site and its children
Retrieves values for a specific field to display for each item
The whole query is shown, and it is described in detail in the following sections.
1 <ViewFields>
2 <FieldRef Name="Title" Nullable="True" Type="Text"/>
3 <FieldRef Name="Comments" Nullable="True" Type="Note"/>
4 </ViewFields>
5 <Lists ServerTemplate="850"></Lists>
6 <Webs Recursive="True" />
7 <RowLimit>15</RowLimit>
8 <![CDATA[
9 <Where>
10 <Gt>
11 <FieldRef Name="Created" Nullable="True" Type="DateTime"/>
12 <Value Type="DateTime"><Today OffsetDays="-7"/></Value>
13 </Gt>
14 </Where>
15 <OrderBy>
16 <FieldRef Name="Created" Nullable="True" Type="DateTime"
17 Ascending="FALSE"/>
18 </OrderBy>]]>
QueryOverride property
Lines 8-19 define the QueryOverride property.
8 <![CDATA[
9 <Where>
10 <Gt>
11 <FieldRef Name="Created" Nullable="True" Type="DateTime"/>
12 <Value Type="DateTime"><Today OffsetDays="-7"/></Value>
13 </Gt>
14 </Where>
15 <OrderBy>
16 <FieldRef Name="Created" Nullable="True" Type="DateTime"
17 Ascending="FALSE"/>
18 </OrderBy>
19 </Query>]]>
In the preceding example:
Lines 8-10 define the query and open the <where> clause.
Line 11 refers to a base type field with the name "Created", and is of field type DateTime.
Line 12 sets the value for this field to be DateTime and sets an offset of -7, meaning that 7 is subtracted from the date that the query filters on.
Lines 13 and 14 close the <where> clause.
Line 15 opens the <OrderBy> clause, which determines the sort order for the fields specified within.
Lines 16 and 17 set the sort order for the "Created" field. The Web Part displays this data in descending order.
ListsOverride property
You can also use a CAML query to retrieve items from SharePoint Foundation 2010 and SharePoint Server 2010 lists. Table 4 shows three CAML statement examples that retrieve items from distinct list types.
Table 4. Three CAML statement examples that retrieve items from distinct list types
List Type | Property Statement |
|---|
Page Libraries |
<![CDATA[
<Lists ServerTemplate="850">
</Lists>
]]>
|
General List base type |
<![CDATA[
<Lists BaseType="0">
</Lists>
]]>
|
A specific type of list |
<![CDATA[
<Lists>
<List ID="{fa564e0f-0c70-4ab9-b863-0177e6ddd247}"/>
</Lists>
]]>
|
In the example, Line 5 defines the ListsOverride property.
5 <Lists ServerTemplate="850"></Lists>
In this case, the query uses ServerTemplate="850" to override the current list in use. You can find an enumeration of available list types in the Lists property in the SharePoint Foundation 2010 SDK.
WebsOverride property
You can use CAML to set the WebsOverride property to retrieve items recursively, as shown in the following code example.
<![CDATA[
<Webs Recursive="True"/>
]]>
Or, you can retrieve items from only the sites specified.
In line 6 of the example, we set the property to retrieve items recursively.
6 <Webs Recursive="True"/>
ViewFieldsOverride property
To display values for any item in the Web Part, set the ViewFieldsOverride property to retrieve data of a specified type from a specified field, as shown in the following code example.
<![CDATA[
<FieldRef Name="Comments" Nullable="True" Type="Note"/>
<FieldRef Name="Created" Nullable="False" Type="User"/>
]]>
Setting Nullable="True" returns items that do not have this column.
In the code sample, lines 1–4 set the ViewFieldsOverride property:
1 <ViewFields>
2 <FieldRef Name="Title" Nullable="True" Type="Text"/>
3 <FieldRef Name="Comments" Nullable="True" Type="Note"/>
4 </ViewFields>
Line 1 opens the <ViewFields> clause, which sets the ViewFieldsOverride property.
Lines 2 and 3 refer to the Title field (a text field) and the Comments field (a note field).
Line 4 closes the <ViewFields> section.
DataColumnRename Property
Use the DataColumnRename property to rename columns programmatically. This property can help you minimize XSLT and schema customization, or to perform bulk or custom column renaming operations. For example, you can rename a compound column name such as KBArticleTitle to a common XSLT transformation variable name such as Title, and remove the need to create a custom XSLT transformation for each custom schema.
Separate column rename values by using semicolons and use the format originalName,newName.
<![CDATA[<property name="DataColumnRenames" type="string">KBArticleTitle,Title</property>]]
| Note |
|---|
If you rename a column with a name that already exists, the rename operation fails. |
Additional Field, Filter, Grouping, and Sorting Options
Set properties in this group to add fields, groupings, grouping and sorting options, filters, and filter options. You can specify fields by their internal name, GUID, a combination of internal name and display name, or GUID and display name.
Define the AdditionalFilterFields and AdditionalGroupAndSortFields properties by using one of the following formats:
internalName
internalName,DisplayName
GUID
GUID,DisplayName
You can also combine AdditionalFilterFields and AdditionalGroupAndSortFields definitions into compound statements, which is useful to set more than one field in a property statement. Use semicolons to separate the fields when combining definitions in one statement, as shown:
internalName;GUID; internalName,DisplayName;GUID,DisplayName
Setting the AdditionalFilterFields property enables you to add a Created filter field to the UI, as shown in the following code example.
<![CDATA[<property name="AdditionalFilterFields" type="string">Created</property>]]
Setting the AdditionalGroupAndSortFields property enables you to add a Created option to the grouping and sorting lists in the UI.
<!CDATA[<property name="AdditionalGroupAndSortFields" type="string">Created</property>]]
Filter Properties
You can use custom properties to extend filter values beyond what the UI supports. Setting or modifying any of the filter field, filter type, filter value, or filter chaining operator properties adds or changes filter behavior in the UI.
| Note |
|---|
Filter properties do not override the UI; they prefill the UI with default values. |
Filter field, filter type, and filter value properties are always of type string:
<property name="FilterField1" type="string" />
<property name="FilterType1" type="string" />
<property name="FilterValue1" type="string" />
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
The following example filter code displays a Created filter in DateTime format and displays items that were created after October 25, 2011:
<property name="FilterField1" type="string">Created</property>
<property name="FilterType1" type="string">DateTime</property>
<property name="FilterValue1" type="string">Today-7</property>
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
Use the following format to set the type parameter in filter operator and filter chaining operator property statements: PropertyName, namespace, Version, Culture, PublicKeyToken.
<property name="FilterOperator1" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterFieldQueryOperator, Microsoft.SharePoint.Publishing, Version=12.0.0, Culture=neutral" PublicKeyToken=71e9bce111e9429c"/>
<property name="Filter1ChainingOperator" type="Microsoft.SharePoint.Publishing.WebControls.ContentByQueryWebPart+FilterField, Microsoft.SharePoint.Publishing, Version=12.0.0.0, Culture=neutral, PublicKeyToken=71e9bce111e9429c">Eq</property>
The valid values for the filter operator and filter chaining operator properties differ, as follows:
The filter operator properties show the And and Or buttons in the UI.
The filter chaining operator properties populate the second field in the Show items when lists in the Additional Filters section of the UI.
Table 5 provides valid values for the filter operator properties.
Table 5. Valid values for filter operator properties
Value | Display Value |
|---|
And | And |
Or | Or |
Table 6 provides valid values for the filter chaining operator properties.
Table 6. Valid values for filter chaining operator properties
Value | Display Value |
|---|
Eq | is equal to |
Neq | is not equal to |
Gt | is greater than |
Geq | is greater than or equal to |
Lt | is less than |
Leq | is less than or equal to |
BeginsWith | begins with |
Contains | contains |