Federated Results Web Parts XSLT
Note
This topic describes functionality that is part of the Infrastructure Update for Microsoft Office Servers. To download the update, see Description of the SharePoint Server 2007 infrastructure update: July 15, 2008.
The search results for federated locations are returned to the search server in a structured XML format (for example, RSS or Atom). The results are formatted and rendered in the federated search Web Parts based on the specified XSLT transformation (XSLT).
This topic provides an overview of the default XSLT for federated locations, and describes how you can customize it to change how the results are displayed in the federated search Web Parts.
Introduction to XSLT
XSL is a programming language that transforms XML into another format or structure, such as HTML. This means that instead of displaying a Web page with static HTML, you can apply the XSLT to an XML document to dynamically generate the HTML. In this scenario, the presentation layer is also separated from the data layer. XSL provides many of the same features found in traditional programming languages, such as variables, functions, iteration, and conditional statements.
For more information about XSLT, see the following resources:
XPath is the language used to specify which elements in the XML to transform, and also to calculate values.
See the following resources for more information:
Customizing the XSLT for a Federated Location
Before walking through the specific XSLT used to display federated search results, you should understand how you can view and modify the XSLT.
You can access the XSLT in two places:
The federated location's definition
The federated Web Part properties
Where you choose to modify the XSLT depends on whether you want it to apply globally to all federated search Web Parts, and in which of the federated search Web Parts you want to display the results.
Modifying the XSLT for a Federated Location
The XSLT for a federated location is specified in the XSL field in the Display Properties section for the federated location.
Note
You must be a Search Service administrator to perform the following procedure.
To access the XSL field for the federated location
On the Search Administration page, click Federated Locations.
On the Manage Federated Locations page, click the Location Display Name for the location you want to modify.
In the Display Information section, uncheck Use Default Formatting in the section for the federated search Web Part you want to change the XSLT for.
Click the ellipsis button (…) for the XSL field. This opens the Text Entry window for the location's Xsl element. You can modify the XSLT directly in this window; however, you may find it easier to copy the code to a file. You can then edit that file by using an application such as Microsoft Visual Studio 2008. After you finish editing the file, you can copy the modified code into the Text Entry window.
Click OK to save your changes, close the Text Entry window, and then click OK to update the location.
You can undo your changes to the XSLT, and revert to the default XSLT specified for the location by selecting the Use Default Formatting check box specified in step 3.
Note
You can also access the location's XSLT directly in the location definition (.fld) file. The XSLT is specified in the Xsl element, contained within the Visualization element of the Location Definition schema.
You should choose this method when you want the custom XSLT to be applied globally to most or all of the federated Web Parts configured to use a specific location. This is because when you modify the federated location's Xsl element, the customized XSLT is used for all federated search Web Parts configured to use that location, unless an individual Web Part's XSL property is customized. We also recommend that you use this method when customizing the XSLT to display results in the Top Federated Results Web Part. This is because you can specify multiple locations for this Web Part, and the customized XSLT may be different for each location.
Modifying the Federated Web Part's XSLT
The XSLT for a federated search Web Part is specified in the Xsl property of the Display Properties section in the Web Part's tool pane. As mentioned in the previous section, we recommend that you use this method only for the Federated Results Web Part.
To access XSL property for the Federated Results Web Part
In your browser, navigate to the results page URL. For example:
http://<ServerName>/results.aspxClick the Site Actions link, and then click Edit Page.
For the Federated Results Web Part instance you want to modify, click the edit arrow to display the Web Part menu, and then click Modify Shared Web Part. This opens the Federated Results Web Part tool pane.
Click the Display Properties arrow.
Clear Use Location Visualization, and then click XSL Editor.
This opens the Text Entry window for the Web Part's XSL property. You can modify the XSLT directly in this window; however, you may find it easier to copy the code to a file. You can then edit that file by using an application such as Visual Studio 2008. After you finish editing the file, you can copy the modified code back into the Text Entry window.
Click Save to close the Text Entry window, and then click OK to update the Federated Results Web Part instance.
You can undo your changes to the XSLT, and revert back to the default XSLT specified for the location by selecting the Use Location Visualization check box specified in step 6.
You can now examine the XSLT used to display federated search results.
XSLT for the Federated Web Part
Enterprise Search in Microsoft Office SharePoint Server 2007 supports two types of federated locations:
Local Search Index SharePoint sites local to the search server.
OpenSearch 1.0/1 The RSS feed for any remote search server's results page, or any searchable feed that supports the OpenSearch standard, and returns search results in structured XML format (for example, RSS or Atom results).
When the results from either location type are displayed in the federated search Web Parts, they appear to be formatted the same. However there are differences in the XML data returned for each location type, which means that there are also differences in the default XSLT specified for each location type. This section provides an overview of the results XML and the XSLT used to transform it for both types of locations.
Local Search Index Locations
You use the Local Search Index location type to show federated results from the local search index on this search server. Before you begin to modify the XSLT applied to the results XML for this location type, you should know what is in the results XML data for local search index location types. You can view the results raw XML data for this location type by using a customized version of the XSLT. The custom XSLT for this task and how to modify the XSLT is described in How to: View the XML Data Returned by Your Federated Location.
Local Search Index Results XML Data
The following code sample shows a portion of the federated results XML data for a local search index location.
<All_Results>
<Result>
<id>1</id>
<title>Local Site</title>
<hithighlightedsummary>
Get Started with Windows <c0>SharePoint</c0> Services!
</hithighlightedsummary>
<hithighlightedproperties>
<HHTitle>My Local Site</HHTitle>
<HHUrl>http://MyLocalSite</HHUrl>
</hithighlightedproperties>
<url>http://MyLocalSite</url>
<urlEncoded>http%3A%2F%2FMyLocalSite</urlEncoded>
<description>This is a local site.</description>
<contentclass>STS_Site</contentclass>
<imageurl imageurldescription="Result of type:document">
/_layouts/images/STS_Site16.gif
</imageurl>
</Result>
…
</All_Results>
If you are familiar with the XML data returned for the Core Search Results Web Part, notice that the results XML data for the local search index location type is very similar, and some of the customizations to the XSLT for both are similar, specifically for the hit highlighting elements, which are:
hithighlightedsummary
hithighlightedproperties
HHTitle
HHUrl
For more information about customizing the Core Search Results XSLT, see Enterprise Search Core Results XSLT Transformation and Chapter 3: Customizing and Extending the Microsoft Office SharePoint 2007 Search (Part 1 of 2).
Another similarity is in how the top-level (root) node is associated with an XSL template, which is where the transformation begins. Here's the Local Search Index locations' XSLT for this:
<xsl:template match="/">
<xsl:call-template name="MainTemplate"/>
</xsl:template>
In the XSLT for OpenSearch locations, the root element is associated with a template, based on the XML format the location's results are returned in. See the Templates section later in this topic for more information about this. This is because there are multiple XML formats for OpenSearch results, so the XSLT must include different processing instructions for different formats. Since Local Search Index results are always returned in the same XML format, the XSLT only needs to include processing instructions for one XML format.
However, aside from the differences called out here, the XSLT for both location types is similar, so most of the information provided in the next section for OpenSearch locations also applies to the XSLT for Local Search Index locations.
OpenSearch Locations
You use the OpenSearch location type to show federated results from the RSS feed for search indexes on remote search servers. Or use it to show federated results from Web sites that support returning results in a structured XML format, such as RSS or Atom.
OpenSearch Results XML Data
As mentioned earlier, it's helpful to know what is in the results XML data. You can view the raw XML data for results from the OpenSearch location by using a customized version of the XSLT. The custom XSLT for this task and how to modify the XSLT is described in How to: View the XML Data Returned by Your Federated Location.
The following code sample shows a portion of the federated results XML data for the RSS feed of a remote search index location.
RSS feed results XML data
<rss version="2.0" xmlns:srrt="https://schemas.microsoft.com/WebParts/v3/srchrss/runtime">
<channel>
<title>Search Results: sharepoint</title>
<link>
http://MyRemoteSite/pages/results.aspx?k=sharepoint
</link>
<description>
Search RSS feed for Microsoft Office SharePoint Server 2007
</description>
<language>en-US</language>
<lastBuildDate>
Mon, 28 Jan 2008 10:42:03 GMT
</lastBuildDate>
<generator>
Microsoft Office SharePoint Server 2007 RSS Generator
</generator>
<ttl>60</ttl>
<image>
<title>Search Results: sharepoint</title>
<url>
http://MyRemoteSite/pages/_layouts/images/homepage.gif
</url>
<link>
http://MyRemoteSite/pages/results.aspx?k=sharepoint
</link>
</image>
<item>
<title>
Get Started with Windows SharePoint Services!
</title>
<link>
http://MyRemoteSite/Lists/Announcements/DispForm.aspx?ID=1
</link>
<description>
<div style="margin-top:5px">
<link rel="stylesheet"type="text/css" href="http://MyRemoteSite/_layouts/1033/styles/portal.css" />
<span class="srch-Icon">
<a href="http://MyRemoteSite/Lists/Announcements/DispForm.aspx?ID=1" title="Get Started with Windows SharePoint Services!">
<img src="http://MyRemoteSite/_layouts/images/STS_ListItem16.gif" alt="Result of type: document" border="0" /></a></span>
<span class="psrch-Description">
Get Started with Windows <b>SharePoint</b> Services!
…
Windows <b>SharePoint</b> Services helps you to be more effective by connecting people, information
…
</span>
<p class="srch-Metadata">
<span class="srch-URL">
<a href="http://MyRemoteSite/Lists/Announcements/DispForm.aspx?ID=1" title="Get Started with Windows SharePoint Services!">
http://MyRemoteSite/Lists/Announcements/DispForm.aspx=ID=1
</a></span></p></div>
</description>
<author>Denise Smith</author>
<pubDate>1/28/2008</pubDate>
</item>
<item>
…
</item>
…
</channel>
</rss>
Familiarize yourself with the results XML data before you make modifications to the XSLT. By understanding the structure of what is being transformed, you can more easily make your change.
Configuration Parameters
The first block of XSLT defines various configuration parameters that may be passed to the transformation at run time.
<xsl:param name="ResultsPerPage">3</xsl:param>
<xsl:param name="IsDesignMode">True</xsl:param>
<xsl:param name="UrlMaxLength">50</xsl:param>
<xsl:param name="SummaryMaxLength">300</xsl:param>
<xsl:param name="ShowMoreLink">true</xsl:param>
<xsl:param name="MoreLink"></xsl:param>
<xsl:param name="MoreLinkLabel"></xsl:param>
<xsl:param name="IdPrefix"></xsl:param>
<xsl:param name="WebpartTitle"></xsl:param>
<xsl:param name="DefaultIconDescription"></xsl:param>
<xsl:param name="BrandingIcon"></xsl:param>
<xsl:param name="IsFirstPage">true</xsl:param>
For more information about parameters in XSLT. see the <xsl:param> Element. As an example of a customization you can make, you can specify a link to an image to display as the branding image in the Web Part's title bar. To do this, you modify the BrandingIcon parameter, as follows.
<xsl:param name="BrandingIcon">http://MyRemoteServer/_layouts/images/customBrandingImage.gif</xsl:param>
For more information about changing what is displayed in the title bar. see How to: Customize the Title and Branding Icon for Federated Search Results.
Templates
Now examine the section of the code where the top-level (root) XML element is associated with an XSL template. (For more information about XSL templates, see the xsl:template element.)
The root element of the results XML data is based on the XML format the location's results are returned in. In the RSS feed results XML data sample, the format is RSS, so the top-level element is <rss>.
Following is a code block from the default XSLT where the root element is associated a template, based on the format specified in the xsl:template element's match attribute.
<xsl:template match="rss">
<xsl:call-template name="MainTemplate">
<xsl:with-param name="Type" select="'rss'"/>
</xsl:call-template>
</xsl:template>
<xsl:template match="rdf:RDF">
<xsl:call-template name="MainTemplate">
<xsl:with-param name="Type" select="'rdf'"/>
</xsl:call-template>
</xsl:template>
<xsl:template match="atom:feed">
<xsl:call-template name="MainTemplate">
<xsl:with-param name="Type" select="'atom'"/>
</xsl:call-template>
</xsl:template>
<xsl:template match="atom2:feed">
<xsl:call-template name="MainTemplate">
<xsl:with-param name="Type" select="'atom2'"/>
</xsl:call-template>
</xsl:template>
When the root element matches the value specified in the match attribute, the template specified in the xsl:call-template element is applied. In this example, the same template, MainTemplate, is associated with all formats; however the value specified for the Type parameter passed to MainTemplate, using the xsl:with-param element, is different for each format.
MainTemplate
You can find the MainTemplate template by searching for the following XSLT fragment.
<xsl:template name="MainTemplate"
Looking at the XSLT in MainTemplate, you can see that it includes the following processing instructions:
Sets the following variables, by using xls:variable elements:
"Rows", containing the collection of results.
"RowCount", containing the number of results, calculated by using the count function.
"ChannelTitle", containing the federated location's title, retrieved from the XML by using the xsl:value-of element. Because the XML node containing the federated location's title is based on the format type, the node name is conditionally selected by using the xsl:choose element in conjunction with the xsl:when element, and the Type parameter value is passed into MainTemplate.
Checks to see if there are any results. This step is included only in the Top Federated Results Web Part, because this Web Part appears only on the first page of results.
Retrieves the federated location's title as specified in the XML data, and sets it to a variable named ChannelTitle.
Checks if there is at least one row of results returned by using the xsl:if element, and if so:
Specifies the HTML to display the data for the federated Web Part's title bar, including the title and branding image. The branding image is retrieved with the GetBrandingImage template specified in the xsl:call-template element here. The GetBrandingImage template verifies only that a value is specified for the BrandingIcon parameter, and if so, returns it.
Calls the MainTemplate.body template, passing in several parameters, including the Rows, RowCount, and Type parameters. The next section provides more information about MainTemplate.body.
Calls the MoreLinkTemplate template, which specifies the HTML to display the More Results link.
MainTemplate.body
The XSLT in this template iterates through each result, and does the following:
Calls various templates to retrieve the result's title, link, and image XML data. You can customize the image displayed for a result in the GetItemIcon template.
Specifies the HTML to display the title, link, and image. The GetSafeHtml template is called for the title here to ensure no unsafe HTML is used.
Calls MainTemplate.description, described in the next section.
MainTemplate.description
The XSLT in this template formats a result's description XML, and specifies the HTML to display it. It includes the following processing instructions:
Calls the GetDescription template to retrieve the result's description XML.
Verifies that the result contains a value for the description, and if so:
Calls the GetPlainTextFromHtml template, to remove any XML from the description. To return HTML within the description, you can customize the XSLT to remove this step.
Calls the TrimIfGreaterThanMax template to reduce the number of characters in the description to the character limit, if one is specified.
Specifies the HTML to display the description. You can customize how the description is displayed in this section of the template.
Customizing the XSLT
There are several scenarios where you may want to customize the XSLT, such as:
You want to make minor changes to the display of federated search results by modifying the existing templates in the default XSLT.
You want to make more complex changes to the display of federated search results by adding new templates to the XSLT.
You need to modify the XSLT to display a property you added to the default set of properties returned in the federated search results.
You want to conditionally change the display of certain federated results, depending on one of the property values that is returned.
You want to modify the display templates to use a custom cascading style sheet class in place of the default cascading style sheet classes.
The following topics walk you through how to modify the federated results XSLT for various customization scenarios:
How to: View the XML Data Returned by Your Federated Location
How to: Customize the Title and Branding Icon for Federated Search Results