Wednesday, September 11, 2013

Customizing Search in SharePoint 2013 using Display Templates


One if not the biggest improvement in SharePoint 2013 is Search. It is such a great improvement over the 2010 version it is really marvelous. With this great improvement comes a minor problem, information about how to customize search is sparsely available. Yes there are many bloggers that show how to do a small customization. But making customizations for a production environment, I noticed this is something else.

There are many little things that are nice to know up front, I found them during many cycles of trial and error.

In this blog posting I will provide a list containing all the steps I took to customize the search experience for a department at the Ministry of Foreign Affairs in The Netherlands. Hoping to save you from the trouble I had to go through finding out how to customize the search experience of SharePoint 2013. The end result should be a new Search Center with a custom search page displaying only your specific content type (in my case “Dossier”), a custom refinement panel and a custom results panel showing search results using a custom display template and a custom hover panel.



  1. Starting of with a clean site collection, create some custom site columns and a content type that uses those site columns. I’d recommend using a naming convention so it will be easy to find your site columns later on.
  2. Now bind the content type to a list and create a new record that uses your newly created content type.
  3. In Central Administration, go to  “Manage Service Applications” –> “Manage Search Service Application” –>”Content Sources”.
    Start a Full crawl on the content source that hosts your list and record (local SharePoint sites) This will trigger SharePoint to create so called “crawled properties”.
  4. Open “Search Schema” Create new “Managed Properties” , creating a link between the managed properties and the crawled properties SharePoint created for you. (If you are using office 365 or you are a site administrator and have no access to Central administration, just create a mapping between one of managed properties that have not been linked to a Crawled Property.)
  5. Create a new “Result Source” (this can be done on both site collection level as in Central Administration). The most important part of creating the result source is fixing the query so that it will return only your specific content type.
  6. Within the Site Collection you created in step 1, create a new Enterprise Search Center. (if you are like me wondering where they hid that button, there are two: gear sign->Site Contents all the way at the bottom and Gear sign->Site settings –> Sites and Workspaces)
  7. Set the Site Collections search Settings so it will point towards the new search center and the results page. Gear Sign –> Site Settings –> Search Settings.
  8. Navigate to the Search Center and Add a New Page, the page should end up in the pages library of the search center:
  9. From within your search center edit the search settings to add a link towards your newly created page. Gear Sign –> Site Settings –> Search Settings –> In “Configure Search Navigation” add a link pointing towards your new page.
  10. You should now have your new tab in the search navigation box
  11. Edit the newly created search page (in my case dossiers.aspx). Configure the Search Results web part so that it will only display the result source you defined in step 5. Select Edit Web Part and then click the button “Change Query” in the drop down box select the result source. (Make sure you click ok on the web part on the web part editing menu and save the page if you miss one of these three your changes are not persisted)
  12. Edit the Search Refinement web part, click “Add Refiners” and select the managed properties that you have configured to be used for refinement. (in my case ModifiedTime SoortZaak and ZaakVerdrag)
  13. Edit the design Template.
    1. From the Search Center root page (Design manager won’t show up if you are on another page). Click the Gear Sign –> Design Manager.
    2. Select Upload Design Files and click the link, this will open the explorer view towards the display templates. Open the Search folder.
    3. In this directory you will find Item Template files: Item_xxx.html and Hover Panels: Item_xxx_HoverPanel.html. You will also see Javascript Files. Do not open or modify a javascript file. This file is auto generated by SharePoint every time a .html file is updated.
    4. Copy the template that matches the end result your after best to a local folder (or desktop).
    5. Change the file name of your copy into Item_MyContentTypeName in my case Item_Dossier. (You could name it something else, just don’t get lost when you can’t find your template back when you need to make a change in a couple of months)
    6. Open the html file into you favorite editor and edit the title, the managedproperties and the html rendering your contenttype.
      the title
      the managed properties
      the new html using the managed properties
    7. Copy the template you created into the search folder, SharePoint should now create a matching .js file. If this doesn’t happen the most probable cause is that there is a exception in the file you’ve created. You can check this at the _layouts/15/DesignDisplayTemplates.aspx page. From the search center home page Gear Sign –> Design Manager –> 5. Edit Display Templates. Look for your template files it should show “Conversion successful”
    8. Fixing the missing managed properties. Now you will probably end up in the situation that one or more of your custom managed properties won’t show. In my example “Notitie” is filled in the record but is not showing up in the display template.
      Go to site settings –> Go to top level site settings –> Search result Types, you will see a magic bar click Update

      It should turn green
    9. The search page should now be able to render all of the managed properties
    10. However if this doesn’t happen please try to repeat step 11 to make sure that the web part doesn’t cache the template and it’s properties. After that check the template, see if it is still good or if SharePoint mangled it.
  14. Altering the Item Hover panel. This modification is very similar to the alteration of the item display template itself. Copy the hoverpanel template html, modify template the same way as you would altering a normal item template. Within the item display template look for the URL that points towards the hover panel and change so that it will point towards your newly created hover panel.
  15. Deploying the template files using a SharePoint solution. Now I didn’t create any fancy feature that would also set all the search settings and do everything magically. Because with the import and export functionality and the great UI, it would just take too long to create a fully automated solution. However, I do have to solve the fact that administrators want to deploy files with a single install solution command. So Create a solution, add a Module to it make sure the feature is scoped on Site (collection) and that the module is an item within the feature.
    The module needs to resemble something like this:

    <?xml version="1.0" encoding="utf-8"?>
    <Elements xmlns="">
    <Module Name="Masterpage" Url="_catalogs/masterpage">
    <File Path="Masterpage\Display Templates\Search\Item_Dossier.html" Url="Display Templates/Search/Item_Dossier.html" Level="Draft" ReplaceContent ="TRUE" Type="GhostableInLibrary" />
    <File Path="Masterpage\Display Templates\Search\Item_Dossier_HoverPanel.html" Url="Display Templates/Search/Item_Dossier_HoverPanel.html" Level="Draft" ReplaceContent="TRUE" Type="GhostableInLibrary" />

    it is important to notice that ReplaceContent is set to TRUE and that the Level attribute is set to Draft. If this is not set SharePoint will figure that the files that got deployed are final and he should not actively do something with it. While we really want SharePoint to pick up the html files and create JavaScript for us.

Good luck!


Side notes

While editing the item display template I expected to have to change the content type id as well. However that didn’t seem to make any difference.
I am mentioning this because I suspect that changing the content type Id will be necessary in other (so far unknown) situations.

Do not edit the template files directly in the search folder always copy them. I haven’t been able to put my finger on it and I’m hoping that this bug will get fixed soon. But for now SharePoint seems to do some encoding over not only the JavaScript files but also over the html files. It will change signs like ‘ into something like &#39; in effect ruining your template. So alter your files somewhere else and copy that file to the search folder. When you notice that your new managed properties do not show up in the search results. Check the file in the display templates\search folder, you got a good chance that your properties look something like this and you’ll need to fix it:


Whenever you make a modification to the item template concerning properties:

  1. Go to the Manage Result Types page (see step 8) and update the properties.
  2. Go and reconfigure the Search Results web part. This will refresh the template so your changes will show up on the screen.

A little trick that I use to check to see that my html files get translated into JavaScript is renaming the .html file in the search folder. The resulting JavaScript file should get an automatic name change. If this doesn’t happen something is wrong. (maybe your files are in a published state or the files has bugs that prevent the transformation)

Columns that do not contain data will not show up in the Crawled properties
My Colleage, Mark van Steenis noticed that he couldn’t find site columns in Central Administration when there was no column in use and filled with data. Solving this is actually simple just connect your content type to a list and fill the columns with anything, then start the crawler.


SharePoint 2013 Design Manager display templates

Introducing Search Schema SharePoint 2013

User Context sensitive searching SharePoint 2013


  1. This comment has been removed by a blog administrator.

  2. Helpful data shared. I am extremely happy to read this write-up. thanks for giving us good info.Great walk-through.I appreciate this post.
    sharepoint 2013 training