Introduction to SharePoint 2013 Display Templates

New rendering techniques for displaying Search results

Matthew McDermott

by Matthew McDermott on 3/24/2014

Share this:

Article Details

Date Revised:

Applies to:
Microsoft SharePoint 2013, Search, spx

SharePoint 2013 introduces a new technique for presenting search results: Display Templates. If you have worked in previous versions of SharePoint and had to modify the look and feel of Search Results, you know how cumbersome it is. In 2013 the new rendering techniques have several distinct advantages.

  • Display templates are HTML and JavaScript rather than XSL
  • Display templates are configured for the Site and Site Collection rather than for a Web part
  • Display templates are applied with rules and logic
  • Display templates are applied to individual result items, not the entire result set
  • Display Templates are used for Results of all kinds, search results, content by search results, and refiners
  • …and the list goes on

In this post I’ll show you the basics of creating a Display Template, and then future posts will focus on the cool stuff you can do once you know these basics. I will assume that you are using a Search Site Collection. If you aren’t, then you will have to tailor your changes accordingly. I also assume that you know how to deal with Crawled and Managed Properties. I have written about this for SharePoint 2010, and it’s not too terribly different in 2013. In fact you can do it from the Site Collection now!

The Business

You have to have a reason to change the look of your results. In my case, I have added a property to the User Profile called Twitter User Name. This way, users can opt in to showing off their social connection to Twitter. The HR department wants to increase social engagement in the company so they have asked my SharePoint team (me) to add the Twitter link to their People Search result. They would like it to link to the users Twitter profile page, as shown in Figure 1. So here we go:

060413_2337_Introductio1.png   Figure 1: Add the user's Twitter information

The Basics

1. From the Search Center, navigate to Site Settings. In the Look and Feel section, choose Design Manager.

2. In Design Manager, choose Upload Design Files.

3. Click the link at the top of the page to open the Master Page Gallery in Windows Explorer. Figure 2 Shows the link.

        060413_2337_Introductio2.pngFigure 2: Click the link to open Master Page Gallery

4. Browse down the folder structure to Display Templates/Search/ and locate the Item_Person.html file. This is the file used for the out-of-the-box People Search result. Notice that there are actually two files named Item_Person. We always work with the HTML file, which you see in Figure 3, leaving SharePoint to manage the JavaScript file. 060413_2337_Introductio3.png

Figure 3: Use the HTML file

5. Copy the Person_Item file to your desktop and rename it to Item_Twitter_Person. (This way, when you copy it back, it won’t overwrite the original file.)

6. Now open the file in a text editor and find the title tag. Change the title to Twitter People Item as shown in Figure 4. 060413_2337_Introductio4.png

Figure 4: Change the title

7. In the next section are a bunch of tags that begin with <mso. These control the metadata for the Display Template. The one you're interested in is the ManagedPropertyMapping tag. You need to add any new custom properties to this tag before you can display that property in the page. This is where you have to decide what Managed Properties from the Search Service you are going to use in your page. In my case the fine IT folks told me it was called TwitterAccountName. So I’ll add that to the end of the line, as shown in Figure 5. Pay attention to the syntax here. (In a later post I’ll discuss more about the syntax of this declaration. For now just duplicate the field name.) 060413_2337_Introductio5.png Figure 5: Add the Managed Property name  

8. Now we need to add the field to the display part of the page. If I were to create a link to Twitter for my own account it would look like this: Twitter: <div><a href=””>MatthewMcD</a></div> What I need to do is swap out my account with a token that will be replaced by the user in the search results. Microsoft introduced a new token that you can use for this purpose

_#= to start and =#_ to end

That combination of characters will tell SharePoint to look at what’s inbetween and treat it like JavaScript. So what you need now is a way to reference the field TwitterAccountName. You do that by referencing theContext of the Current Item in the search results. All put together it looks like this: _#= ctx.CurrentItem.TwitterAccountName =#_. So now your code looks like Figure 6 inserted below the NameValue div: 060413_2337_Introductio6.png    

Figure 6: Example of code

9. Save the file and copy it back to the server by dragging it back to the Search Display Templates folder where you started. If you refresh the Explorer windows you will notice that SharePoint automatically created a matching .js file, as you see in Figure 7060413_2337_Introductio7.png

Figure 7: Matching .js file

10. Now you need to tell SharePoint when to use your new Display Template. You do this with a Result Type. Return to Site Settings and choose Search Result Types from the Site Collection Administration section.        

11. Locate the Person result type, hover click and choose Copy, as shown in Figure 8. 060413_2337_Introductio8.png

Figure 8: Choose Copy

12. Change the name to Twitter Person and change the Action | What should these results look like? to Twitter People Item. Notice in Figure 9 how the Display Template URL changes to the JavaScript sister file SharePoint created. 060413_2337_Introductio9.png

Figure 9: Display Template URL changes

13. Click Save and return to the Search Center to check your work.

14 Execute a search on the People Search vertical and you should see the results of your work, as in Figure 10. 060413_2337_Introductio10.png    

Figure 10: Results

15. So we achieved our goal, but there’s something I don’t like about the result. Oso does not have a Twitter account, so we should not show the “Twitter:” text. This is a simple change and demonstrates the last basic concept for the article.

16. You can open and edit the Display Template on the right of the Explorer window. Then each time you save the file, it will update on the server immediately. So, go ahead, open the file in your text editor right out of SharePoint, as shown in Figure 11. 060413_2337_Introductio11.png    

Figure 11: Open the file

17. Now that you have the file open, you need to add some conditional code so you only write the Twitter tag if the user entered a value. This is super easy. The trick is to tell SharePoint that it is a code block. For that, I’ll use an HTML comment and our special tag again. Figure 12 is what our code looks like now. I added my JavaScript in between the comments and wrapped it around my divs.


Figure 12: New code

18.Return to the Search Center and test the search. You should see that the values only display when they are not blank, as shown in Figure 13.


Figure 13: Values show only when not blank


So what have we learned?

  • You can use a text editor to create Display Templates from copies of the out of the box files.
  • You can embed and emit custom managed properties in your search results.
  • You can run JavaScript in your Display Template for conditional formatting.

Download the file used in this sample:

Topic: Search

Sign in with

Or register