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 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!
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:
Figure 1: Add the user's Twitter information
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.
Figure 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
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.)
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.
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.)
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=”http://twitter.com/MatthewMcD”>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
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 7
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.
Figure 8: Choose Copy
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.
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.
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
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.
Download the file used in this sample: Item_Person_Twit.zip