In the first part of this blog post series about custom search refiner controls, I’ll describe what is minimal needed to create a clean refiner control display template. This template can later be used as a starter’s template for the creation of other refinement controls.
Create a New Search Refiner Control Template
The first thing you’ll need to do, is creating a new HTML file in the Master Page Gallery. The default refiner controls templates are located in: Master Page Gallery / Display Templates / Filters (
http://your-site/_catalogs/masterpage/Display Templates/Filters), but it doesn’t matter where you put you template file in the master page gallery (only the file properties need to be in place). I place my display templates in a separated project folder in the master page gallery. This way it’s easier to find them and they stay grouped together.
The content to start with looks like this:
For this post I set my refinement panel to use my custom template with the Brand result type, but you can use the result type you like.
Important Display Template Property
There is an important property in the search refinement control template that can be used to specify for which types of search data your refinement control is to be used. This is the CompatibleSearchDataTypes property. By leaving the property empty it can be used for whatever data type.
The values that can be applied are the following:
The values need the following prefix and suffix: “;#”. Examples:
Show the Refiner Title
At the moment, the custom refiner control template won’t show anything. This is because the HTML template doesn’t has any output to visualize. In the next steps I’ll explain how to add the collapsible title and the refiner values.
The mark-up can be added inside the DropdownRefinement block. The mark-up contains some objects like ctx.ListData which contains all the refiners for the current results.
The Srch.U.collapsibleRefinerTitle function is used to display the collapsible refiner title.
If you don’t want to have this, you can remove the function call and display the refinement name instead: refinerCatTitle.
Show the Refiners Values
The next step is to show the refiner values of the current search results. The approach that is used in the default SharePoint template is to work with two HTML blocks. One block for the unselected refiners, and one block to be shown with the selected refiners. In this post I’m only going to create the first block with unselected refiner values.
To visualize these refinement items you need to add two arrays (the selected one will be used in the next post), one array for the unselected refiners, and one for the selected refiners.
The following piece of code is used to fill the arrays with the values it retrieved.
Currently only the unselected items array will be used. To visualize the refinement items from the unselected array, you can add an unselected section block to the Container element. In this unselected block a loop need to be created that enumerates all refinement items. The refinement items will be visualized by calling another function ShowRefiner.
The ShowRefiner function looks like this:
The end result of this part is just an enumeration of all the refinement values.
Adding Total Items per Refinement Value
If you want to add the total of items per refiner, you can modify the ShowRefiner function by adding the refinementCount variable to the output.
The next part we’ll add the refinement actions to the each item, so that refining the search results can be tested.
Here you can download display template: Custom Refinement Control.
Blog posts in this series:
- Part 1: Create your first search refiner control template
- Part 2: Adding Refinement Actions to the Custom Search Refiner Control
- Part 3: Working with File Types in the Search Refiner Control Template
- Part 4: Create a dropdown refiner control
- Part 5: The Search Refiner Control Methods Explained
- Part 6: Create a Multi-Value Search Refiner Control
- Part 7: Working with Ranges in the Search Refiner Control