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

Applies to: SharePoint Server 2010

You can use the Content By 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 By Query Web Part, you should consider the branding and site design you want to achieve. Microsoft SharePoint Server 2010 includes three Extensible Style Language (XSL) files that you can modify to render fields in styles that the Content By Query Web Part uses to display the content it aggregates.

This topic identifies the three XSL files the Content By 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 By 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 By Query Web Part.

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 By 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.

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 SharePoint Server 2010 XSL files, as described in the following table.

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

1. Navigate to your site's home page, click Site Actions, and then click Edit Page to check out the page in Edit Mode.

2. In one of the Web Part Zones, click Add Web Part, and then select and add a Content Query Web Part.

3. Click edit, and then click Modify Shared Web Part.

4. Modify properties and add fields to the Content Query Web Part as needed. For more information, see How to: Customize the SharePoint Content By Query Web Part by Using Custom Properties (ECM).

   Note

   When you modify the Content By 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.

5. 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

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

2. 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">
   

See Also

Tasks

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

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

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