How to: Customize the SharePoint Content By Query Web Part by Using Custom Properties (ECM)

  • Article

Applies to: SharePoint Server 2010

You can use the Content By Query Web Part to create custom views of data that is queried from many sources, and present that data all in one place. After you add the Content By Query Web Part to a Web page, you can customize the Web Part's querying behavior, custom lists, and content types by setting custom properties. There are 60 properties and methods available for the ContentByQueryWebPart class, many of which you can customize. This topic introduces some of the properties, and includes syntax and usage examples in Collaborative Application Markup Language (CAML) format that you can add to a .webpart file.

Some Microsoft SharePoint Server 2010 Content By Query Web Part properties are inherited from Microsoft SharePoint Foundation, and others are unique to SharePoint Server 2010. This topic focuses on properties introduced in SharePoint Server 2010. Following are the two basic categories of SharePoint Server 2010 Content By Query Web Part properties:

  • Properties that set or override an aspect of the Web Part's underlying behavior. In some cases, these properties also affect the user interface (UI).

  • Properties that modify the Web Part UI without setting or overriding underlying behavior.

Properties that Modify UI and Behavior

Properties in the first group, such as overrides, are generally more powerful because you can use them to modify the Web Part's behavior. If a user attempts to modify the UI or set another property that could affect the behavior that this property affects, this property "wins" in the UI; it overrides other settings and determines how the Content By Query Web Part behaves. These properties are useful when you want to do the following:

  • Add persistent fields and field options

  • Override the default cross-list query behavior so that changes to fields and field options in the UI persist and cannot be overwritten or broken by other changes

  • Rename long, compound column names into more common XSLT transformation variable names and avoid creating custom XSLT transformations for every schema

Table 1 describes some of the properties that modify UI and behavior.

Table 1. Properties that modify UI and behavior

Property

Description

CommonViewFields

Requests additional fields, which is necessary because the Content By Query Web Part does not return all fields for all items automatically. You must request fields to render in an XSLT transformation.

This property is additive, meaning that you can add more than one CommonViewField to a Content By Query Web Part and extend its base properties, such as FieldDescription and FieldLabel.

QueryOverride

Bypasses limits to query behavior imposed by the Content By Query Web Part UI. Makes it possible to specify the query portion of a cross-list query in CAML.

When the QueryOverride property is set, the UI for filtering, sorting, and grouping appears dimmed in the tool pane. For example, by default the Content By Query Web Part enables three filters, and you might want to add more and ensure that the customized fields and behavior persists in the UI.

WebsOverride

Determines whether the cross-list query should recurse subsites. By default, SharePoint Server 2010 recurses subsites, meaning that the parent site and its child sites are displayed.

When the WebsOverride property is set, the Content By Query Web Part does not recurse, and displays results from only the specified site.

ListsOverride

Overrides the list behavior in SharePoint Server 2010, and supports several types of lists, such as Page Libraries, the General List base type, and specific list types. You can use this custom property to set any list type, even those not enumerated in the UI because the template is not defined at the root or is a base type.

List types are defined in the List element reference topic in the Windows SharePoint Services 3.0 SDK.

ViewFieldsOverride

Gives the Content By Query Web Part the ability to request a set of fields from the query that you specify, instead of making the automatic request in SharePoint Server 2010 for the base fields.

DataColumnRenames

Gives the Content By Query Web Part the ability to rename columns before the data is passed to the XSLT transformation for rendering.

Properties that Modify UI Without Overriding Behavior

Alternatively, you might need lighter-weight options to customize fields, field options, grouping and sorting options, and filter options in the UI. These customizations do not affect the underlying behavior and can be overridden by properties in the first group that do override behavior. Customizations such as these are useful if you want to do the following:

  • Offer more options through a Content By Query Web Part than are initially set when an instance of the Web Part is added to the page

  • Affect only one Web Part that will not likely be subject to an override

  • Make more options available to the end user

Table 2 describes some of the properties in this group.

Table 2. Properties that do not override behavior

Property

Description

AdditionalFilterFields

AdditionalGroupAndSortFields

Includes one or more additional fields (AdditionalFilterFields property) or grouping and sorting options (AdditionalGroupAndSortFields property) that do not normally appear in the UI in the filter drop-down lists. This can be useful if a field is not provisioned as a site column but is present in some lists and should be available in the UI. When this property is set, the UI offers this column for filtering.

FilterField1

FilterType1

FilterValue1

FilterOperator1

Filter1ChainingOperator

Includes functionality to filter values beyond what the UI supports. Use these properties to prefill some UI values, such as when the Web Part is first added to the page. For example, you might want to specify default values, and to filter on the date range relative to today's date.

Approaches to Customizing a Content Query Web Part

There is more than one way to set or modify custom properties in a Content By Query Web Part, and the method you choose depends on your goals and where you are in the site and Web site design process. For example, if you are customizing an existing Page Layout, you can use Microsoft SharePoint Designer 2010 and customize the Content By Query Web Part while you customize the Page Layout. If you are creating a new, customized Content Query Web Part for an existing Page Layout, you can use SharePoint Designer 2010 to add or modify custom properties.

To modify the custom properties of an existing Content By Query Web Part, you can export the .webpart file, make a copy of it and rename the original, modify the custom properties in the copy of the .webpart file, and then import it into a Web Part zone in your page. Renaming the original .webpart file ensures that a copy of the original .webpart file exists for future upgrade scenarios.

To export a .webpart file, set its custom properties, and then import it

  1. Log on to your Web site.

  2. On the Site Actions menu, click Edit Page.

  3. Find the Content By Query Web Part on the page, and then on the Web Part's edit menu, click Export.

  4. Save the .webpart file.

  5. Rename the .webpart file, and then use a text editor or SharePoint Designer 2010 to open the renamed file.

    Note

    Renaming the original .webpart file ensures that a copy of the original .webpart file exists for future upgrade scenarios.

  6. Add or modify properties and property values, and then save your changes.

  7. On the Page menu, point to Add Web Parts, and then click Browse.

  8. Select the Web Part to import from the Web Part List, and then click OK.

  9. Drag the Web Part to a Web Part zone on the page.

Example

Description

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:

  • Internal name of field

  • Internal name of field, field type

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.

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.

Note

To learn more about CAML syntax and commands, see the Collaborative Application Markup Language Core Schemas in the SharePoint Foundation 2010 SDK.

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:

  1. Retrieves a Created field

  2. Sets the query to retrieve items updated in the past seven days and sorts them in descending order

  3. Specifies the list type to query from

  4. Retrieves data recursively from the specified Web site and its children

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

<![CDATA[
   <Webs/>
]]>

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

See Also

Tasks

How to: Customize XSL for the SharePoint Content By Query Web Part (ECM)

How to: Display Custom Fields in a SharePoint Content By Query Web Part (ECM)

How to: Customize RSS for the SharePoint Content By Query Web Part (ECM)

Reference

SPSiteDataQuery

ContentByQueryWebPart