This is a blog post in the series "How to change the way search results are displayed in SharePoint Server 2013 and SharePoint Online".
For an overview of the blog post in this series, go to How to change the way search results are displayed in SharePoint Server 2013.
In the previous blog post, I explained the mechanics of how search results are displayed. In this blog post, we’ll learn:
- How to map your network drive
- Why it’s important to know about managed property names
- About important elements of an item display template
- About hit highlighting
- How hit highlighting works – it is magic!
When working with display templates, you will make life a lot easier for yourself if you map your network drive. By doing this, you’ll be able to work with display templates from Windows Explorer.
I describe how you can map your network drive in this blog.
In the introduction to this series, I explained how site columns and site column values are “transformed” into managed properties and managed property values during crawl. It is important that you can find the name of the managed property that represents a site column because, to add new information to your search results, you’ll need to add the managed property name to an item display template. If you’re unsure of how managed properties are named, see the blog post: From site column to managed property – What’s up with that?
Confusing? Well, don’t despair. I’ll walk you through the steps of how to find and add a managed property name to an item display template in a later blog post.
In my previous blog post, I explained that SharePoint comes with a large number of item display templates. Although these display templates are not 100% identical, they all contain certain elements that control how search results are displayed.
Let's dive right in and open an item display template, for example: Item_Excel. Because I’ve mapped my network drive, I can simply open the file in my favorite HTML editor, Notepad++.
About the <title> tag
The top of the display template has a <title> tag. The text in this tag is what will be shown when you do configurations in the SharePoint UI, for example, when you configure a result type.
The following screenshot shows how the text from the <title> tag in the item display template, Excel Item, is shown in the configuration of the Microsoft Excel result type.
The ManagedPropertyMapping element contains the managed properties that can be used to display the search results. The following syntax is used to store these properties in the item display template:
'<Display template reference name>':<Managed property name>'
The screenshot below shows the default ManagedPropertyMapping element for the Excel Item display template.
Notice that the display template reference name is the same as the managed property name, for example 'Title':'Title' or 'FileType':'FileType'. Even though this might seem a bit confusing at first, having identical names will make it easier to maintain the file.
By default, the managed properties that are included in this element vary slightly for the different item display templates. However, two managed properties that are included in all display templates are HitHighlightedProperties and HitHilightedSummary. I'll talk more about these two properties later in this post.
About the <body> tag
Inside the <body> tag, there is a <div> tag with an ID. By default, the ID for this <div> tag matches the name of the file. In our case, this is Item_Excel.
Any HTML or code that the display template should use to display search results is included inside this <div> tag.
About the hover panel display template variable
I want to point out one variable that’s used inside this block: var hoverUrl. In my previous blog post, I explained how each item display template contains a reference to a hover panel display template. The variable var hoverUrl contains this reference.
The screenshot below shows how var hoverUrl points to the Item_Excel_HoverPanel hover panel display template.
About the icon that shows in search results
I also want to mention the value ctx.CurrentItem.csr_Icon. This value points to the icon that should be displayed next to each search result, for example the Excel icon.
The following screenshot shows how the value ctx.CurrentItem.csr_Icon points to an icon.
In later blog posts I'll show you how you can change this value so that it points to a custom icon.
About the reference to the common item display template
Towards the end of the <div>, a very important line of code is included: _#=ctx.RenderBody(ctx)=#_. In my previous blog post, I explained that this is a reference to the item display template that’s used by all result types.
The following screenshot shows how _#=ctx.RenderBody(ctx)=#_ is used in the Item_Excel display template.
Even if you have never heard of hit highlighting before reading this blog post, I guarantee that you’ve seen the feature in action. However, you might not have given it much thought.
The hit highlighting feature takes the words that a user has entered in a search box and displays them in bold in the search results. That way, users can easily scan search results to see the context in which their query words are found. For example, in the following screenshot I’ve entered "result type" in the search box. In the search results, "result" and "type" are displayed in bold.
By default, hit highlighting is enabled for certain managed properties. To see these managed properties, on a search results page, edit the Search Results Web Part. In the Web Part Tool Pane click to expand the Display Templates section. The properties that are enabled for hit highlighting are listed in the Hit-highlighted properties (JSON) section.
There is a little bit more to it than that, but for now it's important that you know where these managed properties are listed.
Let's go back to my "result type" search and take a closer look at the first search result. That search result was returned because the values in the Title and Project/File Name columns contained the words I was looking for.
As I previously explained, the ManagedPropertyMapping element in the item display template contains the managed properties that can be used to display search results. Based on this, you can understand why "About configuring result types" is displayed. It is because "About configuring result types" is the value of Title in the list item, and Title is one of the managed properties found in the ManagedPropertyMapping element in the display template. The words "result type" are displayed in bold (hit highlighted) because Title is one of the hit-highlighted properties listed in the Search Results Web Part.
But why is "CSH_Configure_result_types…" displayed in the search results? In the list item we can see that this is the value for Project/File Name, but the managed property for that site column is not included in the ManagedPropertyMapping element in display template. Neither is it listed as one of the hit-highlighted properties in the Search Results Web Part. So why is this value displayed?
About the “magical summary” property
If you guessed hit highlighting, you are correct. In addition to the default properties that you saw in the Hit-highlighted properties (JSON) section of the Search Results Web Part, there is a property that contains a summary for each item. This is almost like a magical property, because it stores a summary of each item in the search index. This summary is created under the SharePoint hood, so you don't need to worry about that. What's important is that when I searched for "result type", a match was found in both the Title and this "magical summary" property.
If you are now thinking; Hang on! I understand that the value for Title is displayed because Title is one of the managed properties found in the ManagedPropertyMapping element in the display template. But I don't see any "magical summary" property in the ManagedPropertyMapping element of the display template, so how can the value be displayed?
Well, that is where the two properties HitHighlightedProperties and HitHilightedSummary come into play. The diagram below does not represent how SharePoint actually handles these properties, however you can think about it in the following way:
- The managed properties that are listed in the Hit-highlighted properties (JSON) section of the Search Results Web Part and the "magical summary" property are passed to the HitHighlightedProperties property.
- All values of the HitHighlightedProperties property are passed to the HitHighlightedSummary property.
- A truncated version of the values in HitHighlightedSummary is displayed in the Search Results Web Part.
If you look closely at the search results, you’ll notice that many search results are displayed with three dots at the end.
These dots indicate that these are values from the HitHighlightedSummary property.
If you only want to display a minimum amount of information for each search result, you can rely on the hit highlighting magic and probably be OK with the default way search results are displayed. However, if you want custom information to be displayed for each search result, you will have to do some customization.
In the next blog article, I'll show you the first step in customizing search results: creating a new result type.
Next blog post in this series
How to create a new result type