Export (0) Print
Expand All

How to: Customize the Content Query Web Part by using Custom Properties

You can use the Content 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 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 Office SharePoint Server 2007 Content Query Web Part properties are inherited from Windows SharePoint Services 3.0, and others are unique to Office SharePoint Server 2007. This topic focuses on properties introduced in Office SharePoint Server 2007. Following are the two basic categories of Office SharePoint Server 2007 Content 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 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 field 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.

The following table describes some of the properties that modify UI and behavior.

Property Description

CommonViewFields

Requests additional fields, which is necessary because the Content 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 Query Web Part and extend its base properties, such as FieldDescription.

QueryOverride

Bypasses limits to query behavior imposed by the Content 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 Query Web Part allows 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, Office SharePoint Server 2007 recurses subsites, meaning that the parent site and its child sites are displayed.

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

ListsOverride

Overrides the list behavior in Office SharePoint Server 2007, 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 Query Web Part the ability to request a set of fields from the query that you specify, instead of making the automatic request in Office SharePoint Server 2007 for the base fields.

DataColumnRenames

Gives the Content 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 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 won't likely be subject to an override

  • Make more options available to the end user.

The following table describes some of the properties in this group.

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 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 Office SharePoint Designer 2007 and customize the Content 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 Office SharePoint Designer 2007 to add or modify custom properties.

To modify the custom properties of an existing Content 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.

  1. Log on to your Web site.

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

  3. Find the Content 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 Office SharePoint Designer 2007 to open the renamed file.

    NoteNote:

    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.

This section describes custom properties and includes formatting and code examples for custom property statements and CAML queries within a Content 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 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 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.

NoteNote:

For a list of additional field types that the CommonViewField property can request, see the SPFieldType enumeration in the Windows SharePoint Services 3.0 SDK. Office SharePoint Server 2007 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 Query Web Part always requests. The base fields request default columns by GUID, and in the UI they appear as the Site Column names. The following table lists the 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 Office SharePoint Server 2007 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 Query Web Part behavior. To override a behavior, construct a CAML query that defines the conditions you want to set.

NoteNote:

To learn more about CAML syntax and commands, see the CAML Reference in the Windows SharePoint Services 3.0 SDK.

In the following example, we demonstrate setting custom properties for the Content Query Web Part 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 Windows SharePoint Services 3.0 and Office SharePoint Server 2007 lists. The following table shows 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 Windows SharePoint Services 3.0 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 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>]]
NoteNote:

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.

NoteNote:

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 25th, 2006:

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

The following table provides valid values for the filter operator properties.

Value Display Value

And

And

Or

Or

The following table provides valid values for the 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

Community Additions

ADD
Show:
© 2015 Microsoft