Customizing Content Query Web Parts by Using Custom Properties in Office SharePoint Server 2007

Summary:  Learn how to customize the Content Query Web Part by setting the CommonViewFields property, the QueryOverride property, and the DataColumnRenames property.

Office Visual How To

Applies to:  2007 Microsoft Office System, Microsoft Office SharePoint Server 2007

Joel Krist, Akona Systems

December 2007

Overview

You can use the Content Query Web Part to create custom, dynamic views of data that is queried from many sources, and you can present that data in one location. You can customize the behavior of the Content Query Web Part by setting custom properties. This Office Visual How To shows you how to set the CommonViewFields custom property, the QueryOverride custom property, and the DataColumnRenames custom property.

See It Customize Content Query Web Part Using Properties

Watch the Video

Length: 10:13 | Size: 11.2 MB | Type: WMV file

Code It | Read It | Explore It

Code It

This example uses a document library named Project Status Reports to show how to customize the Content Query Web Part. The Project Status Reports document library uses a custom site content type named Project Status Report, which is in the Project Status Reports content type group. The Project Status Report content type contains the site columns that are shown in Table 1.

Table 1. Project Status Report content type site columns

Column Data Type

Project Name

Text

Project Owner

Text

Project Status

Text

Project Status Summary

Text

To show how to customize the Content Query Web Part by using custom properties, this section describes five steps:

  1. Adding the Content Query Web Part to a Web page on an Office SharePoint Server 2007 site.

  2. Configuring the Content Query Web Part to work with the Project Status Reports document library and with the Project Status Report content type.

  3. Exporting the Content Query Web Part to a .webpart file.

  4. Editing the exported .webpart file and setting the custom properties of the Content Query Web Part.

  5. Importing the edited .webpart file to a Web page on an Office SharePoint Server 2007 site.

Adding a Content Query Web Part to a Web Page

First, add an instance of the Content Query Web Part to your Office SharePoint Server page.

Note

The Content Query Web Part is available with Microsoft Office SharePoint Server 2007 but not with Windows SharePoint Services 3.0.

To add an instance of the Content Query Web Part to a Web page

  1. On your Office SharePoint Server 2007 site, click Site Actions, and then click Edit Page.

  2. In a Web Part zone, click Add a Web Part.

    Figure 1. Add a Web Part to a Web Part zone

    Add a Web Part to a Web Part zone

  3. In the Add Web Parts dialog box, select the Content Query Web Part check box, and then click Add.

    Figure 2. Add Web Parts dialog box

    Add Web Parts dialog box

Configuring the Content Query Web Part

Next, edit the properties of the Content Query Web Part so that it displays content from the Project Status Reports document library.

To edit the properties of the Content Query Web Part

  1. In the Content Query Web Part, click edit, and then click Modify Shared Web Part.

    Figure 3. Modify Shared Web Part

    Modify Shared Web Part

    The Content Query Web Part pane (Figure 4) shows the Web Part property categories.

    Figure 4. Web Part pane

    Web Part pane

  2. In the Content Query Web Part pane, click Query, and then, in the Source section, select Show items from the following list.

    Figure 5. Set the source property

    Set the source property

  3. Click Browse. In the Select List or Library dialog box, click Project Status Reports, and then click OK.

    Figure 6. Select list or library

    Select list or library

  4. In the Content Query Web Part pane, in the List Type section, in the Show items from this list type list, select Document Library.

  5. In the Content Query Web Part pane, in the Content Type section, in the Show items of this content type group list, select Project Status Reports. In the Show items of this content type list, select Project Status Report.

    Figure 7. Set list type and content type properties

    Set list type and content type properties

  6. In the Content Query Web Part pane, click Appearance. In the Title box, type Projects to Watch. Click OK to save your changes.

    Figure 8. Set the title property

    Set the title property

    The Content Query Web Part, now titled Projects to Watch (Figure 9), displays the documents that are currently in the Project Status Reports document library.

    Figure 9. Display all documents

    Display all documents

Exporting the Content Query Web Part

The Content Query Web Part exposes many properties that you can customize, but only some of them are available through the Content Query Web Part pane. To edit the custom properties of an existing instance of the Content Query Web Part, you export the Web Part to a .webpart file, and then edit the .webpart file.

To export the Content Query Web Part

  1. On the Content Query Web Part, click edit, and then click Export.

    Figure 10. Exporting the Web Part

    Exporting the Web Part

  2. In the File Download dialog box, click Save. In the Save As dialog box, type a file name and select a location for the .webpart file. Click Save to save the file.

Editing the Exported .Webpart File

The exported .webpart file is a text file that contains XML that describes the properties of the Web Part. You can edit it by using any text editor or by using an XML-aware editor such as Microsoft Office SharePoint Designer 2007 or Microsoft Visual Studio. When you edit the custom properties in the .webpart file, there are some things to remember:

  • You must specify any column names that you want to use by their internal Office SharePoint Server names. The internal name of a column might not be the same as the name that is displayed in the Office SharePoint Server user interface. For example, spaces in a column name are encoded as _x0020_ in the internal name. You can see the internal name of a column by viewing the query string parameter in a Site Column page, or by viewing the Content Query Web Part code after filtering on the column. To view the column name in the Web Part code, set the Web Part to filter on the column, export the Web Part, and then view the name of the column as it is referenced in the filter properties.

  • All XML markup that is included in a <property /> tag must be enclosed in a <!CDATA[ ]]> block.

  • The XML markup must not include extra spaces between tags.

To demonstrate, edit the custom properties of the Content Query Web Part .webpart file so that the Web Part displays only projects where the Project Status column is set to "Requires Attention".

To edit the custom properties of the Content Query Web Part .webpart file

  1. Set the value of the QueryOverride property.

    The QueryOverride property makes it possible to bypass limits to query behavior that are imposed by the Content Query Web Part user interface by allowing the query part of a cross-list query to be specified in Collaborative Application Markup Language (CAML). When the QueryOverride property is set, the Content Query Web Part user interface for filtering, sorting, and grouping appears dimmed in the Web Part pane.

    Open the .webpart file, locate the QueryOverride property, and edit it as shown in the following code.

    <property name="QueryOverride" type="string">
    <![CDATA[<Where><Eq><FieldRef Name="Project_x0020_Status" 
      Nullable="True" Type="Text"/><Value Type="Text">Requires 
      Attention</Value></Eq></Where><OrderBy><FieldRef Name="Created" 
      Nullable="True" Type="DateTime" Ascending="FALSE"/></OrderBy>]]>
    </property>
    

    This CAML query causes the Content Query Web Part to query for Project Status Reports where the Project Status column is set to "Requires Attention", and then to order the result set by creation date in descending order. This query is simple for demonstration purposes. You could specify the same simple query and ordering by using the Content Query Web Part user interface. However, specifying the query by using the QueryOverride property locks the query so that users cannot change it. You can also use the QueryOverride property to create complex queries that are not supported by the Content Query Web Part user interface.

  2. Set the value of the CommonViewFields property.

    The Content Query Web Part does not automatically return all fields for all items. You can use the CommonViewFields property to request that specific fields are rendered.

    Locate the CommonViewFields property in the .webpart file, and then edit it as shown in the following code.

    <property name="CommonViewFields" type="string">
      Project_x0020_Status_x0020_Summary, Text;
    </property>
    

    This markup requests the Project Status Summary column. This causes the data in the column to be available for rendering. The internal column name is specified, followed by its data type of Text.

  3. Set the value of the DataColumnRenames property.

    The Content Query Web Part uses XSLT transformations to render its contents. The DataColumnRenames property gives the Content Query Web Part the ability to rename columns before the data is passed to the XSLT transformation for rendering.

    Locate the DataColumnRenames property in the .webpart file, and then edit it as shown in the following code.

    <property name="DataColumnRenames" type="string">
      Project_x0020_Status_x0020_Summary,Description;
    </property>
    

    This markup renames the Project Status Summary column to "Description". Description is one of the column names used in the default XSLT transformation that the Content Query Web Part uses to format the rendering of items. Renaming the Project Status Summary column to Description allows rendering of the contents of the Project Status Summary column without you having to edit the default XSLT transformation.

  4. Save the modified .webpart file.

Importing the Edited .Webpart File

After you edit the Content Query Web Part .webpart file, you import it to a page on the Office SharePoint Server site.

To import the customized Content Query Web Part

  1. On your Office SharePoint Server site, click Site Actions, and then click Edit Page.

  2. On the page editing toolbar, click Page, point to Add Web Parts, and then click Import.

    Figure 11. Importing the Web Part

    Importing the Web Part

  3. In the Add Web Parts pane, click Browse. In the Choose file dialog box, locate the folder that contains the edited .webpart file, select it, and then click Open. In the Add Web Parts pane, click Upload.

    Figure 12. Add Web Parts

    Add Web Parts

  4. At the bottom of the Add Web Parts pane, in the Add to list, select a Web Part zone, and then click Import.

The customized Content Query Web Part is added to the selected Web Part zone. The Web Part displays a link to the project status report document and the text from the Project Status Summary column for Project Status Reports whose status is set to "Requires Attention".

Figure 13. Customized Content Query Web Part

Customized Content Query Web Part

Read It

You can use the Content Query Web Part to display a dynamic set of items based on a query. The Web Part enables you to set presentation options to determine how items are displayed on the SharePoint page. The items that are displayed by the Content Query Web Part always reflect the most current set of items retrieved by the query that the page viewer is authorized to see. The query runs when the page that contains the Content Query Web Part is viewed. If new content is added, and it meets the query criteria, the Content Query Web Part displays it automatically. The Content Query Web Part exposes many properties that you can set to control its behavior. This article describes how to customize the Content Query Web Part by setting the CommonViewFields property, the QueryOverride property, and the DataColumnRenames property. The steps are:

  1. Adding the Content Query Web Part to a Web page on an Office SharePoint Server 2007 site.

  2. Configuring the Content Query Web Part to work with a specific document library and content type.

  3. Exporting the Content Query Web Part to a .webpart file.

  4. Editing the exported .webpart file and setting the custom properties of the Content Query Web Part.

  5. Importing the edited .webpart file to a Web page on an Office SharePoint Server 2007 site.

Explore It