Creating a Custom SharePoint IA Refiner – Part One

When working with SharePoint refiners, you will sooner or later need to create a refiner that has more than one value mapped to a refinement.

This is the first article in a series of two looking at custom IA refiners in SharePoint – the second of which will look at a more complex set of scenarios for refining content.

For an example, take a look at the following extract from the out of the box Result Type refiner:

In the refiner item level display template, the mapping object (map) is extended to include a new property called “Access” (which is the value returned from the loadResource method shown above) which is then attributed the “RefinerName” property value “FileType” (the managed property to use for this refinement) and then the relevant array of file types are stored against the “RefinemnetValues” property.

This means any result returned in search with one of these file types are aggregated and covered in the refinement option (Access).

We can use this same logic to create our own associated mappings for when we need more than one refinement value covered in a refiner option and we will now take some time to look into how this can be achieved.

The Scenario

We will be looking at a simplified business scenario to explain how to put together the pieces of the puzzle:

  • All items with the following content types should be returned as a Bid Report:
    • Bid Initial Findings Document
    • Bid Proposal Feedback Document
    • Bid Lessons Learnt Document
  • Any items found within one of the following sites should be returned as Essentials and Help:

The Approach

We will be looking at how we can build a refiner for the scenario above (the bid documents which we want to cover in our refiner do not share the same parent Content ID – indeed if they did, it would be possible to do a “contains” query on the content type id, however this would also have the effect of returning all children, which may not be what you want).

The first thing we need to do is create the JavaScript object that will contain the refiner mapping values. Something like the following example (obvious declare the objects (myCompany, myCompany.myProject etc.. first):

Now we can create a new mapping function by following the example set out by the OOB Result Type refiner:

So now we need to add the conditional logic which is used to call the mapping function. This needs to be added as a new “else if” in the item level display template for the refiner as shown in the example below:

With this in place we are 75% of the way there – you just need to do some wrap up tasks and you have a custom refiner ready to use with multiple mappings.

First of all make sure we clear off any set refiners when the “Show All” link is clicked (after an active refinement). We do this again by amending the display template and following the OOB refiner’s lead:

Finally, the last thing we need to do is to make sure that are refinements are done using an “Or” query and not an “and”

After you have setup your refiner and set the name (MyRefinerName) and mapped the managed property, you can associate it with the Display Template containing your changes and then you should get the desired results:



This approach allows you to map multiple refinement values to a single refinement mapping (e.g. doc, docx, rtf, dot to an MS Word refinement item) and it is fairly simple to use with the following caveats:

  • Display Templates are a breeding ground for duplicated code – modularise methods that you introduce and call out to them from the Display Template.
  • You should probably modularise the mapping function somewhere centrally and make it so you can parse in mappings
  • Centralise constants used so that they can be altered in one place easily and quickly

In the second part of this series, I will look at how you can create a completely custom refiner to work with a more complicated business requirement.

Creating a Custom SharePoint IA Refiner – Part One

One thought on “Creating a Custom SharePoint IA Refiner – Part One

Leave a Reply

%d bloggers like this: