How to: Customize XSL for the Content Query Web Part

Article
10/16/2013

You can use the Content Query Web Part to aggregate content from multiple data sources across your Web site, and then present it all in one place. Before you configure and customize the Content Query Web Part, you should consider the branding and site design you want to achieve. Microsoft Office SharePoint Server 2007 includes three Extensible Style Language (XSL) files that you can modify to render fields in styles that the Content Query Web Part uses to display the content it aggregates.

This topic identifies the three XSL files the Content Query Web Part uses and describes how they work; identifies the templates and variables that you can modify; and describes how to modify the files so that the Content Query Web Part renders data with the look and feel that you specify.

The following table lists and describes the three XSL files that describe the Content Query Web Part.

File Location Description

File	Location	Description
ContentQueryMain.xsl	`\Style Library\XSL Style Sheets\ContentQueryMain.xsl`	Contains logic that generates the appropriate calls to the Header and Item templates for each item. Contains functions that help designers modify the Item and Header XSLT transforms. Receives all the content, parses it, and sends appropriate pieces to the ItemStyle and Header templates. Maintains the structure of the Content Query Web Part. Stores data retrieved when querying content in the path `/dsQueryResponse/Rows/Row`.
ItemStyle.xsl	`\Style Library\XSL Style Sheets\ItemStyle.xsl`	Contains templates that define how to display an item. These templates receive and process one row of data at a time, ensuring that the style and data in the item rows is consistent. You can retrieve data about a row by using the `@Property` directive.
Header.xsl	`\Style Library\XSL Style Sheets\Header.xsl`	Contains templates that define how to display a header and ensure the consistency of group headers. Templates specified in Header.xsl receive the next item row to process, usually the first row in a group unless there are multiple columns. If there are multiple columns, the templates receive the first row of the column. You can retrieve data about the next item row by using the `@Property` directive. You can use the `$Group` parameter that contains the groupby column name and the `$GroupType` that represents the column type of the groupby column.

ContentQueryMain.xsl

\Style Library\XSL Style Sheets\ContentQueryMain.xsl

Contains logic that generates the appropriate calls to the Header and Item templates for each item.
Contains functions that help designers modify the Item and Header XSLT transforms.
Receives all the content, parses it, and sends appropriate pieces to the ItemStyle and Header templates.
Maintains the structure of the Content Query Web Part.
Stores data retrieved when querying content in the path /dsQueryResponse/Rows/Row.

ItemStyle.xsl

\Style Library\XSL Style Sheets\ItemStyle.xsl

Contains templates that define how to display an item. These templates receive and process one row of data at a time, ensuring that the style and data in the item rows is consistent.

You can retrieve data about a row by using the @Property directive.

Header.xsl

\Style Library\XSL Style Sheets\Header.xsl

Contains templates that define how to display a header and ensure the consistency of group headers.

Templates specified in Header.xsl receive the next item row to process, usually the first row in a group unless there are multiple columns. If there are multiple columns, the templates receive the first row of the column.

You can retrieve data about the next item row by using the @Property directive. You can use the $Group parameter that contains the groupby column name and the $GroupType that represents the column type of the groupby column.

By default, the following templates are included in the ItemStyle.xsl and Header.xsl files. The Header.xsl file contains Group style definitions, while the ItemStyle.xsl file contains definitions that apply to row items in the Content Query Web Part. These styles correspond to the options available in the Group and Item style drop-down lists that appear when you choose styles in the Style Library.

Note

In the following tables, templates are listed in the order they appear in the files.

File Name	Template	Content Query Web Part Action
ItemStyle.xsl	Default	LinkImage is on the left. LinkTitle is at the top. Description is below.
ItemStyle.xsl	NoImage	LinkTitle is at the top. Description is below.
ItemStyle.xsl	TitleOnly	Item contains only the LinkTitle.
ItemStyle.xsl	Bullets	Item contains the LinkTitle pre-pended by a bullet.
ItemStyle.xsl	ImageRight	LinkImage is on the right. LinkTitle is at the top. Description is below.
ItemStyle.xsl	ImageTop	LinkImage is above. LinkTitle is in the middle. Description is below.
ItemStyle.xsl	ImageTopCentered	LinkImage is above and centered. LinkTitle is in the middle. Description is below.
ItemStyle.xsl	LargeTitle	LinkImage is on the left. LargeLinkTitle is at the top. Description is below.
ItemStyle.xsl	ClickableImage	Contains only the LinkImage.
ItemStyle.xsl	NotClickableImage	Contains only Image, without a link.
ItemStyle.xsl	FixedImageSize	LinkImage with a size constraint on the left. LinkTitle is at the top. Description is below.
ItemStyle.xsl	TitleWithBackground	Contains the LinkTitle with a background color.

File Name	Template	Content Query Web Part Action
Header.xsl	DefaultHeader	Displays the Group Header in medium font size.
Header.xsl	LargeText	Displays the Group Header is in large font size.
Header.xsl	SmallText	Displays the Group Header is in small font size.
Header.xsl	Band	Displays the Group Header with a squared background color.
Header.xsl	Centered	Centers the Group Header.
Header.xsl	Separator	Inserts a line between the Group Header and content below.
Header.xsl	Whitespace	Inserts white space between the Group Header and content below.

Each template includes two sections of processing instructions:

<xsl:variable> sections that process the data and ensure correct formatting.
<div> sections that render the HTML and include the data.

The template code for the ImageRight template follows, annotated with comments:

///Declares an XSL template named ImageRight that

///processes row style elements defined as ImageRight.

- <xsl:template name="ImageRight" match="Row[@Style='ImageRight']"
mode="itemstyle">

///The <xsl:variable> sections process and ensure correct formatting of the data.

///This section declares the variable named SafeLinkUrl, includes instructions to call the OuterTemplate.GetSafeLink function, and includes the LinkUrl expression to scope the call to the UrlColumnName parameter.
  - <xsl:variable name="SafeLinkUrl">
       /// The OuterTemplate.GetSafeLink variable passes in the UrlColumnName that represents the column name containing the ItemUrl.
    - <xsl:call-template name="OuterTemplate.GetSafeLink">
        <xsl:with-param name="UrlColumnName" select="'LinkUrl'" />
      </xsl:call-template>
    </xsl:variable>

///This section declares the variable named SafeImageUrl and calls the OuterTemplate.GetSafeStaticUrl function.
  - <xsl:variable name="SafeImageUrl">
    - <xsl:call-template name="OuterTemplate.GetSafeStaticUrl">
        <xsl:with-param name="UrlColumnName" select="'ImageUrl'" /> 
      </xsl:call-template>
    </xsl:variable>

///This section declares the variable named SafeImageHtml and calls the OuterTemplate.GetColumnDataForUnescapedOutput function, and passes the 'PublishingRollupImage' and 'Image' parameter values to the template rule.
  - <xsl:variable name="SafeImageHtml">
    - <xsl:call-template name="OuterTemplate.GetColumnDataForUnescapedOutput">
        <xsl:with-param name="Name" select="'PublishingRollupImage'" /> 
        <xsl:with-param name="MustBeOfType" select="'Image'" /> 
      </xsl:call-template>
    </xsl:variable>

///This section declares the variable named DisplayTitle, includes calls to the OuterTemplate.GetTitle function, and passes the @Title and 'LinkUrl' parameter values to the template rule.
  - <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>

///This section declares the variable named LinkTarget and tests whether it should open the target URL in a new window. If the test returns True, then the template rule processes the instruction to open the target URL in a new window.
  - <xsl:variable name="LinkTarget">
      <xsl:if test="@OpenInNewWindow = 'True'">_blank</xsl:if> 
    </xsl:variable>

///The <div> sections define the data to render and provide instructions on how to render it. This code block defines item data, and uses the OuterTemplate.CallPresenceStatusIconTemplate function to verify whether it should create an icon.
- <div class="item">
    <xsl:call-template name="OuterTemplate.CallPresenceStatusIconTemplate" />
///The <xsl:if test> instruction supplies a condition for the XSLT engine to evaluate. If the test evaluates to True after converting it to a Boolean value, the ItemStyle renders the content.
    - <xsl:if test="string-length($SafeImageUrl) = 0 and string-length($SafeImageHtml) != 0">
      - <div class="image-area-right">
          <xsl:value-of disable-output-escaping="yes" select="$SafeImageHtml" /> 
        </div>
      </xsl:if>
    - <xsl:if test="string-length($SafeImageUrl) != 0">
      - <div class="image-area-right">
        - <a href="{$SafeLinkUrl}" target="{$LinkTarget}">
            <img class="image" align="left" border="0"   src="{$SafeImageUrl}" alt="{@ImageUrlAltText}" /> 
          </a>
        </div>
      </xsl:if>
  - <div class="link-item">
    - <a href="{$SafeLinkUrl}" target="{$LinkTarget}" title="{@LinkToolTip}">
       <xsl:value-of select="$DisplayTitle" /> 
      </a>
      - <div class="description">
          <xsl:value-of select="@Description" /> 
        </div>
     </div>
  </div>
  </xsl:template>

Several functions are available for use in the <xsl:variables> section of the Office SharePoint Server 2007 XSL files, as described in the following table.

Function	Description
`OuterTemplate.GetSafeLink`	When the user passes in the `UrlColumnName(`the column name containing the `ItemUrl` value), this function returns a URL that is safe to display to the item. If the URL is not safe to display, the function returns a blank URL. If the item is not streamed, the function returns the `CopyUtil` URL.
`OuterTemplate.GetSafeStaticUrl`	When the user passes in `UrlColumnName` (the name of the column where the URL is stored), if the URL is safe to display, the function returns the URL. If the URL is not safe to display, then the function returns a blank URL.
`OuterTemplate.GetColumnDataForUnescapedOutput`	When the user passes in `Name` (the column name from which to retrieve the data), this function gets column data for unescaped output. When the user passes in `MustBeOfType` (the expected column type), the function returns the content if the column is of the correct type. Otherwise, it does not return any data.
`OuterTemplate.GetTitle`	When the user passes in `Title` (the data in the `Title` column), this function returns a title. If `Title` is blank, the page name either appears as blank or as the title.
`OuterTemplate.FormatColumnIntoUrl`	When the user passes in the `UrlColumnName` (the column name that contains a URL), this function returns the URL contained in the column.
`OuterTemplate.FormatValueIntoUrl`	When the user passes in a `Value` that represents the data found in a Windows SharePoint Services 3.0 URL column type, the Windows SharePoint Services 3.0 URL column returns the URL and the alt text. Returns the URL contained in the column.
`OuterTemplate.Replace`	If the user does one of the following: Passes in `Value`, and represents the string to replace on Passes in `Search`, and represents the string to match on Passes in `Replace`, and represents the string to replace the match with This function returns the appropriate search and replace text.
`OuterTemplate.GetPageNameFromUrl`	When the user passes in `UrlColumnName` (the column name of the item URL), the function returns the page name from the URL.
`OuterTemplate.GetPageNameFromUrlRecursive`	Helper method for `GetPageNameFromUrl`.
`OuterTemplate.GetGroupName`	When the user passes in the value of the `GroupName` column, the function returns the group name in the appropriate format. If the value is empty, it returns a blank group name. When the user passes in the value of the `GroupType` column (the column type for the group), the function returns the page name if the type is `URL`.
`OuterTemplate.CallPresenceStatusIconTemplate`	If the `@SipAddress` attribute exists on the current row, it generates the appropriate markup to create a presence icon for Microsoft Office Outlook 2007 or Microsoft Office Communicator 2007.

To add a Content Query Web Part and customize Content Query Web Part XSL

Navigate to your site's home page, click Site Actions, and then click Edit Page to check out the page in Edit Mode.
In one of the Web Part Zones, click Add Web Part, and then select and add a Content Query Web Part.
Click edit, and then click Modify Shared Web Part.
Modify properties and add fields to the Content Query Web Part as needed. For more information, see How to: Customize the Content Query Web Part by using Custom Properties.

Note

When you modify the Content Query Web Part, there are two drop-down lists in the Styles section: one for Group style, and another for Item style. These list items are defined by templates in the ItemStyle.xsl and Header.xsl files.
Modify values of select statements, variables, and expressions by editing the XSL, using the reference information in this topic as a guide. For example, you can modify values of select statements in the <div> section to instruct the expression to resolve to another variable.

To create an item style

Identify a style that is similar to the one you want to create.

Copy the style and change the name and match property values:

<xsl:template name="ImageRight" match="Row[@Style='ImageRight']" mode="itemstyle">
<xsl:template name="ImageRight2" match="Row[@Style='ImageRight2']" mode="itemstyle">

Share via

How to: Customize XSL for the Content Query Web Part

To add a Content Query Web Part and customize Content Query Web Part XSL

To create an item style

See Also

Tasks

Additional resources