Displaying Custom Fields in Content Query Web Parts in Office SharePoint Server 2007

Summary: Learn how to display custom fields in the Content Query Web Part by setting the CommonViewFields custom property and editing the default XSLT transformation used to render items.

Office Visual How To

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

Joel Krist, Akona Systems

September 2007

Overview

You can use the Content Query Web Part to create custom, dynamic views of data that is queried from many sources, and present that data all in one place. You can display custom fields with the Content Query Web Part by setting custom properties and editing the default XSLT transformation. This how-to article demonstrates how to display custom fields in the Content Query Web Part by setting the CommonViewFields property and editing the default XSLT transformation, which is used by the Content Query Web Part to format the rendering of items.

See It Display Custom Fields in Content Query Web Parts

Watch the Video

Length: 12:40 | Size: 20.5 MB | Type: WMV file

Code It | Read It | Explore It

Code It

This how-to article uses a document library named Project Status Reports to demonstrate how to display custom fields with 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 listed in Table 1.

Table 1. Project Status Report site columns

Column Data Type

Project Name

Text

Project Owner

Text

Project Status

Text

Project Status Summary

Text

The following sections show how you can customize the Content Query Web Part to display custom fields. The process includes seven 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 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 CommonViewFields custom property of the Content Query Web Part to request the Project Status Report content type custom fields.

  5. Editing the default XSLT transformation, which is used by the Content Query Web Part to display the Project Status Report content type custom fields.

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

  7. Configuring the imported Web Part to use the new XSL style.

Adding a Content Query Web Part to a Web Page

Note

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

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

  1. On a Web page in a SharePoint site, click Site Actions, and then click Edit Page. The page is placed in edit mode.

  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. Click Add to add the Web Part to the selected Web Part zone.

    Figure 2. Add Web Parts dialog box

    Add Web Parts dialog box

Configuring the Content Query Web Part

This procedure shows how to configure the Content Query Web Part.

To modify the properties of the Content Query Web Part to display content from the Project Status Reports document library

  1. On 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 Tool Part shows Web Part property categories.

    Figure 4. Content Query Tool Part

    Content Query Tool Part

  2. Expand the Query category. In the Source section, click Show items from the following list.

    Figure 5. Set source property

    Set source property

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

    Figure 6. Select List or Library dialog box

    Select List or Library dialog box

  4. Do the following:

    1. In the List Type section, in the Show items from this list type box, click Document Library.

    2. In the Content Type section, in the Show items of this content type group box, click Project Status Reports. In the Show items of this content type box, click Project Status Report.

    Figure 7. Set list type and content type properties

    Set list type and content type properties

    In the Additional Filters section, set Show items when to Project Status is equal to Requires Attention Or Project Status is equal to Might Need Attention And <no filter> (Figure 8).

    Figure 8. Set filters

    Set filters

  5. Expand the Presentation section. In the Group items by box, click Project Status, and then click Show groups in descending order.

    Figure 9. Set grouping property

    Set grouping property

  6. Expand the Appearance section. For Title, type Projects to Watch as the title of the Web Part.

    Figure 10. Set title property

    Set title property

  7. Click OK in the tool part to save the changes to the Web Part properties.

    The Content Query Web Part displays the documents currently in the Project Status Reports document library that have a status of Requires Attention or Might Need Attention, and groups the items by their status.

    Figure 11. Display all documents

    Display all documents

Export the Content Query Web Part

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

To export an existing instance of the Content Query Web Part

  1. In the Web Part, click edit, and then click Export.

    Figure 12. Export Web Part

    Export Web Part

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

Edit the Exported .Webpart File

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

  • You must specify any column names you use by their internal 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, if a column name contains spaces, each space is 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 inside a <property/> tag must be enclosed in a <![CDATA[ ]]> block.

  • Do not include extraneous spaces between tags in the XML markup.

You can display custom fields with the Content Query Web Part. This how-to article shows the steps for modifying the properties in the Content Query Web Part .webpart file so that the Web Part displays Project Status Report content type custom columns.

To modify the properties in the Content Query Web Part .webpart file to display Project Status Report content type custom columns

  1. Set the value of the CommonViewFields property. The Content Query Web Part does not return all fields for all items automatically. You can use the CommonViewFields property to request specific fields to render. Locate the CommonViewFields property in the .webpart file, and then edit it to look like the following.

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

    This markup requests the Project Name, Project Owner, and Project Status Summary columns, to make the data in the columns available for rendering. Each internal column name is specified, followed by its data type. The name/type pairs are separated by semicolons.

  2. Save the modified .webpart file.

Editing the Default XSLT Transformation

You can specify Content Query Web Part group and item styles in the Styles section of the Presentation category in the Content Query Tool Part.

Figure 13. Styles properties

Styles properties

The Content Query Web Part uses the ItemStyle XSLT file that is located in the site collection's Style Library to render items. By editing the ItemStyle XSLT file, you can add a custom item style to enable the Content Query Web Part to render the Project Status Report content type custom fields.

To edit the ItemStyle XSLT file by using Office SharePoint Designer 2007

  1. Start Office SharePoint Designer 2007.

  2. On the File menu, click Open Site.

  3. In the Open Site dialog box, type the URL of the Office SharePoint Server site, and then click Open.

  4. On the View menu of the SharePoint site, click Folder List, expand Style Library, and then expand XSL Style Sheets.

    Figure 14. XSL Style Sheets node

    XSL Style Sheets node

  5. Locate and double-click the ItemStyle.xsl file to open it. SharePoint Designer prompts that the file is under source control and asks if it should check out the file. Click Yes.

  6. Scroll to the bottom of the ItemStyle.xsl file and insert the following markup after the last </xsl:template> tag and before the </xsl:stylesheet> tag.

    <xsl:template name="CustomStyle" match="Row[@Style='CustomStyle']"
    mode="itemstyle">
      <xsl:variable name="SafeImageUrl">
        <xsl:call-template name="OuterTemplate.GetSafeStaticUrl">
          <xsl:with-param name="UrlColumnName" select="'ImageUrl'"/>
        </xsl:call-template>
      </xsl:variable>
      <xsl:variable name="SafeLinkUrl">
        <xsl:call-template name="OuterTemplate.GetSafeLink">
          <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
        </xsl:call-template>
      </xsl:variable>
      <xsl:variable name="DisplayTitle">
        <xsl:call-template name="OuterTemplate.GetTitle">
          <xsl:with-param name="Title" select="@Title"/>
          <xsl:with-param name="UrlColumnName" select="'LinkUrl'"/>
        </xsl:call-template>
      </xsl:variable>
      <xsl:variable name="LinkTarget">
        <xsl:if test="@OpenInNewWindow = 'True'" >_blank</xsl:if>
      </xsl:variable>
      <div id="linkitem" class="item">
        <xsl:if test="string-length($SafeImageUrl) != 0">
          <div class="image-area-left">
            <a href="{$SafeLinkUrl}" target="{$LinkTarget}">
              <img class="image-fixed-width"
                src="{$SafeImageUrl}" alt="{@ImageUrlAltText}" />
            </a>
          </div>
        </xsl:if>
        <div class="link-item">
          <div class="description">
            Project Name:
            <xsl:value-of select="@Project_x005F_x0020_Name" />
            <br></br>
            Project Owner:
            <xsl:value-of select="@Project_x005F_x0020_Owner" />
            <br></br>
            Project Status Summary:
            <xsl:value-of
              select="@Project_x005F_x0020_Status_x005F_x0020_Summary" />
          </div>           
          <xsl:call-template
            name="OuterTemplate.CallPresenceStatusIconTemplate"/>
            <a href="{$SafeLinkUrl}" target="{$LinkTarget}"
              title="{@LinkToolTip}">
              <xsl:value-of select="$DisplayTitle"/>
            </a>
        </div>
      </div>
    </xsl:template>
    

    This markup defines a style named CustomStyle that displays the Project Name, Project Owner, and Project Status Summary, and a link to the item's document. Notice that the Project Status Report column names here are encoded differently from how they were previously in the .webpart file for the Content Query Web Part CommonViewFields custom property. This difference relates to the way certain characters are encoded when they are passed as XML to the XSL to be rendered. One way to see exactly what field names should be sent to the XSL is to insert the following markup into the ItemStyle.xsl file. This markup renders the field names. After the correct field names are determined, you can remove this markup from the XSL file. To see the field names to use in the XSL file, add the following markup to the XSL shown previously, as the first item in the new custom style.

    <xsl:template name="CustomStyle" match="Row[@Style='CustomStyle']"
    mode="itemstyle">
      <xsl:for-each select="@*">
        P:<xsl:value-of select="name()" />
      </xsl:for-each>
    …
    
  7. Check in and publish the changed ItemStyle.xsl file in SharePoint Designer.

Importing the Edited .Webpart File

This procedure shows how to import the customized Content Query Web Part.

To import the customized Content Query Web Part to a page on the SharePoint site

  1. Click Site Actions, and then click Edit Page.

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

    Figure 15. Import Web Part

    Import Web Part

  3. In the Add Web Parts pane, click Browse. In the Choose File dialog box, navigate to the folder that contains the .webpart file you modified earlier, click the file, and then click Open.

    Figure 16. Add Web Parts

    Add Web Parts

  4. In the Add Web Parts pane, click Upload.

  5. After the Web Part is uploaded, in the Add Web Parts pane, select the Web Part zone to add the Web Part to, and then click Import. The customized Content Query Web Part is added to the selected Web Part zone.

Configuring the Imported Web Part to Use the New XSL Style

At this point, the Web Part looks like it did before: It displays the documents currently in the Project Status Reports document library that have a status of Requires Attention or a status of Might Need Attention, and groups the items by their status.

To make the Web Part use the new XSLT transformation

  1. If the Web page is not already in edit mode, click Site Actions, and then click Edit Page.

  2. On the Content Query Web Part, click edit, and then click Modify Shared Web Part.

  3. In the Content Query Tool Part, expand the Presentation category. In the Styles section, in the Item style box, click CustomStyle.

    Figure 17. Select custom item style

    Select custom item style

  4. In the Web Part pane, click OK to apply the change.

    The Content Query Web Part uses the custom XSLT transformation to render the custom Project Status Report content type fields.

    Figure 18. Customized rendering

    Customized rendering

Read It

You can use the Content Query Web Part to display a dynamic set of items based on a query. The Content Query Web Part enables you to set presentation options that determine how items are displayed on the finished page. The items 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 is run whenever 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 automatically displays it. By default, the Content Query Web Part does not return all fields for items returned in a query. This visual how-to article demonstrates how to display custom fields in the Content Query Web Part by setting the CommonViewFields custom property and editing the default XSLT transformation used to render items. The steps include:

  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 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 CommonViewFields custom property of the Content Query Web Part to request the Project Status Report content type custom fields.

  5. Editing the default XSLT transformation used by the Content Query Web Part to display the Project Status Report content type custom fields.

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

  7. Configuring the imported Web Part to use the new XSL style.

Explore It