Azure / Office 365 / SharePoint Development / Search

Part 1: Create Your First Search Refiner Control Template

October 21, 2013

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:

Once you save this template the JavaScript file gets created and the template will be visible in refinement configuration panel.

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.

Refiner Settings

Refiner Settings

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:

  • Text
  • Integer
  • Decimal
  • DateTime
  • YesNo

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.

To show the refiner title, you need to add some JavaScript and HTML mark-up to the template. The mark-up that you need to add looks like this:

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.

Refiner Title

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.

Refiner values

Refiner 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.

Refiner values with total items per refiner

Refiner values with total items per refiner

Part 2

The next part we'll add the refinement actions to the each item, so that refining the search results can be tested.

Download

Here you can download display template: Custom Refinement Control.

Blog posts in this series:

Comments

  • Pingback: Creating Custom Refiner Control Display Templates for SharePoint 2013 - Elio Struyf()

  • Hi, Can you explain what are selected and unselected refiners?

    • SC Vinod,

      When you do a search, you’ll retrieve a set of results and a corresponding set of refiners to refine the results. This first set are the unselected refiners.
      Once you refine the results, this first set of refiners will be gone, because you retrieve a new set of results, and they will be called the selected refiners. Depending on the search results, this can vary from only on selected refiner, to multiple ones so that you can refiner deeper.

      Here is an example:
      Unselected / selected refiners

      I hope this cleared things up, if not, feel free to ask.

      Regards,
      Elio

  • Pingback: Creating Custom Refiner Control Display Templates for SharePoint 2013 - @eliostruyf()

  • Hi Elio,
    Thanks for nice article . I have a display template refiner that uses dynatree however when i uncheck a refine it works and when i check it again, i see that ListData doesnt return that refiner anymore. Do you have any idea how ListData gets generated and how to control it in code?

    Your help is really appreciated
    Arash

    • Kevin,

      ListData in the refiner context, contains all the available refiners for you current result set. So it means that for the current set of results, the refiner can’t be used, but this doesn’t explain the behavior you’re experiencing.

      is the URL correctly updated with the actions you perform? Are the results returning correct data?

      Regards,
      Elio

  • Senthil

    How can I set Static Filter values for SPContentType refiner group ? I have some content types created and I need to show it static and not change when the search result changes in the Refinement Panel.

  • gopal nayak

    Hi Elio,
    I have kept the level of html file as draft and level of javascript file as published. It works fine for me . Why i need to write the event receiver?

    • If you are going to provision only the HTML files, you’ll need an event receiver to trigger an update for the JavaScript file. You could also work by only provisioning the JavaScript template instead, that way you don’t need an event receiver.

  • Pingback: Display template custom document properties explained - @eliostruyf()

  • Dear Elio Struyf,
    How can i get Refinement Value with count “0” like contoso(0), means default refinement value

    • Bijou Mon,

      You would not get this value back from search, so you will not be able to display that sort of information.
      By development you could retrieve that information from a list and map that in your refiner control. That is the only option you have.

      Regards,
      Elio

  • Hi Elio,
    I’ve used the code you provided in the link however I’m not able to see the values in Refinement panel when I tried to use the choose refiner option. What am I doing wrong?

  • Pingback: How to Update your Refinement Web Part? | Mine Share.Point()

  • PooLP

    Hi Elio,
    it’s possible to get a list of “date”, not a range value, with DateTime data type ?
    Thanks

  • Jason Gomes

    Hi, very much appreciate the effort on this tutorial. Well Done!

  • kalaiyarasan

    Hi, Is possible to display the selected refiner name above the search box.
    Like below senario.

    • Yes that will work, but when you are rendering your selected refiners outside of the refiner control (which is in your case underneath the searchbox). You cannot work like this:

      You will have to replace this to the actual element like this:

      Regards,
      Elio

      • kalaiyarasan

        Hi,
        Can you tell me, how to get the selected refiners from outside of the control?

        • If you retrieve the client control like this:

          You can check the refiners that are in place via the DataProvider its querystate object:

          But this is not what you would need in your example. What you have to do from within the refiner template, is to place the HTML mark-up outside the control. You built this from within the template, that means you know the selected refiners.

  • Jerry

    Hello,
    Great article. I am new to SharePoint and am tasked with creating refiners. I have a SharePoint list and have created a Refinable managedProperty on one of the columns. I am trying to use Part 3 of your articles to group the newly created Refiner under the FileType section. I am not sure how to add the Refinable property to the code. I am also using the STS_ListItem_GenericList as a RefinementValue. Any suggestions would greatly be appreciated. Thank you.

    • If I understand it correctly, you just want to show an extra refiner. For this you do not need to create a new template, you will have to configure your managed property to be used as a refiner in the refinement web part.

      • Jerry

        Hello Elio,
        Thank you for your reply.
        So I do know how to create a refiner using managed properties.  What I am wondering is how to group that new refiner like you did with FileType and only show a count for it.  I don’t want to show the values, just a count. Thanks again, the articles have been a great help to me.
        Jerry

        From: Disqus
        To: jwandr1@yahoo.com
        Sent: Tuesday, January 26, 2016 4:55 AM
        Subject: Re: Comment on Part 1: Create Your First Search Refiner Control Template
        #yiv6918923705 #yiv6918923705 a:hover, #yiv6918923705 a:hover span {color:#1188d2!important;}#yiv6918923705 .yiv6918923705button-cta:hover {color:#ffffff!important;background-color:#1188d2!important;}#yiv6918923705 .yiv6918923705button-cta:hover span {color:#ffffff!important;}#yiv6918923705 #yiv6918923705 #yiv6918923705 #yiv6918923705outlook a {padding:0;}#yiv6918923705 body {width:100% !important;}#yiv6918923705 .yiv6918923705ReadMsgBody {width:100%;}#yiv6918923705 .yiv6918923705ExternalClass {width:100%;display:block;}#yiv6918923705 @media screen and ( _filtered_a ){#yiv6918923705 html {}#yiv6918923705 .yiv6918923705content {width:100%;}#yiv6918923705 table {border-collapse:collapse;}#yiv6918923705 h2.yiv6918923705headline {font-weight:700;font-size:20px!important;margin-bottom:5px;}#yiv6918923705 .yiv6918923705button-cta {display:block!important;padding:0!important;}#yiv6918923705 div.yiv6918923705header {padding-top:20px;}#yiv6918923705 div.yiv6918923705footer {padding-bottom:20px;}}#yiv6918923705 #yiv6918923705 p.yiv6918923705mod-tools a:hover {color:white!important;background:#8c989f!important;}#yiv6918923705 @media screen and ( _filtered_a ){#yiv6918923705 td.yiv6918923705avatar, #yiv6918923705 td.yiv6918923705spacer {width:38px!important;}#yiv6918923705 td.yiv6918923705avatar img, #yiv6918923705 td.yiv6918923705spacer img {width:28px!important;}}”If I understand it correctly, you just want to show an extra refiner. For this you do not need to create a new template, you will have to configure your managed property to be used as a refiner in the refinement web part.” | |
        | |  Settings | |
        |   |

        | |

        | |
        |
        A new comment was posted on Elio Struyf
        |
        | |
        |
        | |
        Elio Struyf
        If I understand it correctly, you just want to show an extra refiner. For this you do not need to create a new template, you will have to configure your managed property to be used as a refiner in the refinement web part. 7:55 a.m., Tuesday Jan. 26 | Other comments by Elio Struyf |   |
        |
        |   | Reply to Elio Struyf |   |

        |
        |   |

        |

        | Elio Struyf’s comment is in reply to Jerry: |
        |   |
        | | Hello,
        Great article. I am new to SharePoint and am tasked with creating refiners. I have a SharePoint list and have created a Refinable managedProperty …Read more |
        |
        | |

        | |

        | |
        | You’re receiving this message because you’re signed up to receive notifications about replies to jwandr1. You can unsubscribe from emails about replies to jwandr1 by replying to this email with “unsubscribe” or reduce the rate with which these emails are sent by adjusting your notification settings. | | |

        | |

  • Pingback: Part 2: Adding Refinement Actions to the Custom Search Refiner Control - @eliostruyf()

  • Pingback: Part 3: Working with File Types in the Search Refiner Control Template - @eliostruyf()

  • Pingback: Create a Multi-Value Search Refiner Control - Elio Struyf - @eliostruyf()

  • Pingback: SharePoint 2013 Search Info – Kathryn Birstein's Blog()