How to: Display Custom Fields in a Content Query Web Part

A Content Query Web Part displays a dynamic view of content on a page in your Microsoft Office SharePoint Server 2007 site. The Web Part runs a query that can span lists and sites in your site collection, and then presents the results of that query on the page. You can, for example, use this Web Part to display the five most recently published articles in your Web site, regardless of where they are stored.

The Web Part has two major aspects: Query and Presentation. Query determines what content you want to show and Presentation determines how you want to style and present the content. You can also attach rules so that only items of a certain type that fit a certain set of rules are shown in the Web Part.

In the tool pane, you can do the following:

• Select the scope of the query. You can configure the Web Part to query items across the entire site collection, from a specific site in the site collection, or a particular list.

• Select the type of list to query items from.

• Specify which content types the Web Part should display.

• Select additional filters to control what content the Web Part displays. For example, one filter may be used to show only Article Pages that were authored by a particular user.

• Select sorting and grouping options to determine the order in which items appear.

• Select styling options to control how the Web Part presents items and group headers.

By default, the XSL style sheet that controls the presentation of the Content Query Web Part renders the Title, Description, ImageUrl, and LinkUrl columns (if present) of the items the query returns. The Web Part renders the ImageUrl and LinkUrl columns as an image and as a hyperlink, respectively. The Content Query Web Part uses XSL style sheets to render these columns by default.

If you want to query for custom content types and render specific columns from those content types in the Web Part, you need to perform some minor customization in the .webpart file.

This topic explains how to include additional columns in the Web Part's query and how to programmatically instruct the Web Part to rename columns to names the default XSLT transformation expects, and then render the columns using the default XSLT transformation styles.

To understand the steps involved in this customization, let’s consider a scenario. Let's say you have a Knowledge Base Articles content type with the following columns:

• KB Title (Text)

• Product (Text)

• Version (Text)

• Status (Choice)

You associate a document library titled Knowledge Base Articles with the content type that contains Knowledge Base articles. You want to display the Knowledge Base articles content in a Content Query Web Part on your home page, display the Title column as the Title field, and display the Product column as the Description field in the Web Part. To do this, perform the following steps.

To display custom fields in a Content Query Web Part

1. Add a Content Query Web Part to a page.

   • In the Query section, set the Source to show items from the Knowledge Base Articles document library (list). Set the list type and content type accordingly.

   • In the Presentation section, set the Item Style to Title and description.

2. Edit the properties in the Web Part file to display custom fields. To access the .webpart file for the Web Part, on the Web Part's edit menu, click Export.

   • Office SharePoint Server 2007 generates a .webpart file with the complete set of properties that are available for this Web Part. The .webpart file is an XML file that you can edit using a text editor.

3. In the .webpart file, locate the CommonViewFields property. Use this property to specify the additional fields you want to display in the Web Part. Add the internal names of the columns and the type.

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

   Note

   You cannot use your columns' display names in this property. You can find the internal column names by checking the properties of the column in the list or document library. Right-click the column, and then click Properties. The internal name of a column appears in the Address (URL) property after 'Field='. In the Knowledge Base Articles scenario, the columns are Knowledge Base Article and Product and their internal names are KB_x0020_Title and Product, respectively.

4. Map these internal column names to the columns' Title and Description present in the XSLT transformations. To do this, edit the DataColumnRenames property.

   <property name="DataColumnRenames" type="string">KB_x0020_Title,Title;Product,Description</property>
   

   Note

   The default XSLT transformations can render the following four fields: Title, Description, LinkUrl, and ImageUrl. In your DataColumnRenames property, verify that the names you specify match the names in the XSLT transformations; that is, Title, Description, LinkUrl, and ImageUrl.

5. Save the .webpart file locally.

6. In the Web page, delete the Content Query Web Part you added in step 1.

7. Import the .webpart file and add the Web Part to your page. To import the .webpart file, click Page, click Add Web Parts, and then click Import. Browse to the .webpart file, and then click Upload.

8. Drag the Web Part to the appropriate zone in the page. The Web Part should display the Knowledge Base Title and the product name.

If you want the Status or the Version column to appear in addition to the KB title and product, modify the XSLT transformation and add the rendering for the additional columns.

See Also

Tasks

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

Other Resources

Common Page and Site Customization Tasks