HOW-TO: Customize SharePoint’s Core Search Results Web Part

The purpose of this post is to share the process that I’ve begun to follow in my own work related to search customization and to provide an opportunity for you to share what’s worked for you, as well.

The post assumes that you’re generally familiar with how search results are customized using the SharePoint search web parts. There are numerous resources available for the mechanics of search result customization within SharePoint. For example, Matt McDermott has a good series of posts giving an example of customization of search results for images (see parts 1, 2, 3, and 4). His series does a good job of explaining how the various components of SharePoint’s search architecture (e.g. managed properties, scopes, etc.) fit together and are configured. There are also numerous examples of the XSL that you can use in various instances to achieve a desired result.

Here’s my process:

Step 1: Ditch the OOB “XSL Editor” button

The core search results web part has a nice big friendly XSL Editor button that pops up a text editor to modify the XSL used to modify the search results.

The button is so big and dominant on the admin panel it practically begs you to click it. My advice? Don’t. It will waste your time and annoy you with its clunky editing and slow refreshes. Instead, use the XSL Link option found in the Miscellaneous properties and provide a reference to your XSL transformation stored in an external file:

So where do you put the actual XSL files? I suggest you store your XSL transformations in a document library. You can use one of the existing ones (e.g. the XSL Style Sheets document library if you’re using the publishing features) or you can create your own. There are several benefits to storing the XSL in a document library instead of embedded within the web part:

• Better reusability. If you’re going to have multiple search interfaces throughout your site and want to customize all of them, it makes sense to have them all refer to a common XSL file. No sense updating all those web parts for every little XSL tweak – unless you REALLY enjoy web part administration.
  
• Versioning and content approval. Web part configuration information – that is, an instance’s properties stored as XML – is not versioned along with a page. Even if you’ve got publishing turned on or are using web part pages stored in a document library with versioning turned on, changes to web parts stored in the page are not versioned along with the page (unlike changes to the page’s metadata via field controls). You can mitigate some of the impact of this on your search configuration by storing your XSL transformations in a document library with versioning enabled. In addition, the OOB content approval features will also carry through to your search results: that is, if content approval is enabled on your document library and an unapproved change is made to the XSL, the search results for all users who do not have permissions to view drafts in that DL will be unaffected.
  
• Development experience. Maybe this one is obvious, but if you choose to store the XSL in the web part itself, you’ll be fighting the OOB text editor for the XSL, or at least end up doing plenty of cutting/pasting into it. The postbacks it requires are also slow. If you store the XSL in a file in a document library, you can open the DL in Explorer view and simply open the XSL directly in your editor of choice, then refresh your search results page after you save the file to see the effect of your changes.
  
• Deployment options. If it bugs you to have to hit the database to access the XSL file, deploy it as a module in a feature and have it be a ghosted file in the document library. This gives you the performance boost of a file-system-based customization while enabling the items mentioned above.

Step 2: Start with a canned XSL file

The IT Leader's Guide to Multicloud Readiness

This guide provides practical key insights and important factors to consider to make informed decisions in your multicloud journey.

Download the Guide

I have three template XSL files that I always use to start the customization process, each with a different purpose.

oobtransform.xsl (download)

This file contains the out-of-the-box XSL transformation provided by SharePoint. I simply pulled it out into a file for cases when the project I’m working on involves mostly small modifications to the OOB configuration.

rawxml.xsl (download)

This file contains no transformation at all, and instead simply emits the XML that is returned by the search query. MSDN’s documentation refers to this approach. This file is valuable when you want to see the exact information (including markup within elements) that is returned.

showcolumns.xsl (download)

This file contains XSL that displays the information returned from the search query in a tabular format. This is probably the file I use the most when making sure that all managed properties are being returned correctly, etc. The output from search when this XSL is used looks something like this:

Step 3: Ensure any additional properties are included

The next step I typically follow is to configure the search results to include all necessary managed properties. These may be properties that I’ve configured myself, or they may be ones that SharePoint provides automatically. In either case, inclusion of the properties is specified using the Selected Columns property of the core results web part:

Clicking the “…” button launches a dialog that displays the information a little better:

To add columns to your results, simply add additional Column elements as children of the Columns element. Remember that since
you’re dealing with XML, the column names are case-sensitive and must match exactly how the managed property is defined in the SSP.

When I’m adding columns, I typically set the core results web part to use the showcolumns.xsl file mentioned above. When I add the reference to the additional column (or columns), I can quickly verify that they’re showing up as expected in the search results.

Step 4: Customize the XSL to your desired output

Lastly, now that you’ve got your web part set to read the XSL from a file, and are also sure that it’s bringing back the proper data, simply customize the XSL to provide the desired presentation.

This is the process I usually follow in customizing the output of the core search results web part. Hopefully it helps provide you with some thoughts as you’re doing the same.