March 24, 2011 1 Comment
One of the quickest and easiest ways to begin customizing the search experience with SharePoint 2010 is to customize the refinement panel web part. If you’ve aren’t familiar with what I’m talking about it is web part that shows on the left hand side of search results page. Each of the sections, are ‘refiners’ which are basically just metadata – and below each refiner the available values that have been entered for content that is being returned in your search result. In this screenshot you’ll see the refinement panel that was displayed when I did a search for ‘contoso’
What is being shown in the screenshot is the default refiners that are displayed for SharePoint search. The refiners allow me to perform a very general search and then click on the refiners to basically filter my results. I can start with a very broad search and then keep refining until I get to what I’m looking for.
But in many organizations, they might want to display their own values here instead of the out of the box ones. The refinement panel uses XML to display the results, so if you wanted to change what you see – it only takes a few steps.
1) Go to your search results page in your Search Center and put it in edit mode. Then edit the Refinement Panel web part.
2) Expand the ‘Refinement’ section. After the field that says ‘Filter Category Definition’ click the ellipsis button which will bring up an editor that allows you to more easily see the code.
I know, there’s no formatting for the XML. It is pretty terrible to look at. You can try to parse it out on your own if you enjoy that kind of thing. I don’t – I’ve found the easiest way to clean up the code is to paste it into Visual Studio 2010. I’ve experimented with a few other editors, and Visual Studio 2010 is the best one.
3) Assuming you are us VS2010, you can open up any project (or create a new one) and Add a New Item. Choose to add an XML file (under the data section). You can name it whatever, because you don’t really need to save it. Then paste your code in and it will all be automagically formatted for you!
QUICK TIP! Visual Studio will add the following code to any new XML file: <?xml version=”1.0” encoding=”utf-8”?> You’ll want to remove this before you paste your code in. If you don’t, it will cause the Refinement Panel to error because that line is already included in the XML you are pasting in from the web part. SharePoint doesn’t like it if it sees two of those lines at the top of your XML.
4) This is going to be a very basic example and we are going to configure the refinement panel to only show the Author refinement. To do this we want to everything inside the <FilterCategories> tag except line 85. In other words, when you are done your XML should look like this:
<?xml version="1.0" encoding="utf-8"?>
<Category Title="Author" Description="Use this filter to restrict results authored by a specific author" Type="Microsoft.Office.Server.Search.WebControls.ManagedPropertyFilterGenerator" MetadataThreshold="5" NumberOfFiltersToDisplay="4" MaxNumberOfFilters="20" SortBy="Frequency" SortByForMoreFilters="Name" SortDirection="Descending" SortDirectionForMoreFilters="Ascending" ShowMoreLink="True" MappedProperty="Author" MoreLinkText="show more" LessLinkText="show fewer" />
It should be pretty obvious what most of the tags do here – but the most important one is MappedProperty. In this case, the refiner is looking at the Author managed property. But really you could set this to be whatever you wanted. So if you had a custom field that you wanted to refine on, no problem! All you’d need to do is add a managed property, and copy/paste the line in the XML which defines the Author refiner, and rename it to match the name of your managed property. Obviously update the other values too – like title and description.
Don’t know how to create a managed property? Check out my blog post on the topic:
5) Copy and paste your new XML from VS2010 back into the text editor in SharePoint. Then his the OK button on the text editor.
6) Now here’s the tricky part that trips people up. Before this will work you need to remove the check from the box at the bottom of the ‘Refinement’ section in the web part properties that says ‘Use Default Configuration’ – if you don’t do this, your changes will not be applied!
7) On the web part properties panel, hit the Ok button. Then you’ll need to press the Check In button on the ribbon.
8) Run a new search and you’ll see that your refinement panel has been customized! If you don’t see results, there could be a couple reasons why. First, make sure that there’s enough items being returned in the search which contain the refiner you are looking for. I’m not sure of the exact number needed, but generally at least 5 will do the trick. Second, if that isn’t the issue you might want to double-check your XML. It is very unforgiving by nature.
This is one of the more common search customizations I’m doing these days for clients. As a final thought, my recommendation is that if you plan on a field being used as a refiner it is best if it isn’t free-text. That means something like a Choice or Managed Metadata field works best.
The other tip I’d suggest is when customizing the refinement panel, don’t try to do 50 refiners all at once. It never seems to end well. I suggest starting with a couple, confirm they work, and then add a few more. Repeat that until you are done. Slow and steady win the race!
Final thought – remember you can always just add the out of the box refinement panel to the page if you want to get back to the original. Or, just go back into your custom web part and check the box again to use the default configuration. Just remember if you check that box again it will overwrite the changes you made to the XML so you’ll have to start over again to reapply your changes. That’s why once I get my refinement panel web part customized the way I like it – I export it out just in case!