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

Applies to: SharePoint Server 2010

A Content By Query Web Part displays a dynamic view of content on a page in your Microsoft SharePoint Server 2010 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 from 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 By Query Web Part renders the Title, Description, ImageUrl, and LinkUrl columns (if present) of the items that the query returns. The Web Part renders the ImageUrl column and the LinkUrl column as an image and as a hyperlink, respectively. The Content By 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 must 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 by using the default XSLT transformation styles.

To understand the steps involved in this customization, consider a scenario in whichyou 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 By 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 By Query Web Part

1. Add a Content By 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.

   SharePoint Server 2010 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 by using a text editor.

3. In the .webpart file, locate the CommonViewFields property. Use this property to specify the additional fields that 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 the display names of your columns 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 that are 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 By Query Web Part that 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 column 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.

Note

The previous example shows you how to edit an individual Web Part on one page to include custom fields in the rendered output. However, you can also make changes to Web Parts by using an editor such as Microsoft SharePoint Designer 2010. SharePoint Designer 2010 is a good tool to use if you want to customize a Web Part that is used on a page layout, and automatically include that custom Web Part in pages that are created by using that layout. You can also add customized Web Parts to the Web Part gallery, which makes them available for dragging and dropping into Web Part zones of new pages.

See Also

Tasks

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

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

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

Concepts

Common SharePoint Web Part and Field Control Customization Tasks (ECM)