SharePoint 2013 Search

(For more resources related to this topic, see here.)

Features of SharePoint 2013 – Result types and design templates

Both result types and design templates are new concepts introduced in SharePoint 2013. Kate Dramstad, a program manager from the SharePoint search team at Microsoft, describes both concepts in a single, easy-to-remember formula: result types + design templates = rich search experience .

When we perform a search we get back results. Some results are documents, others are pictures, SharePoint items, or just about anything else. Up until SharePoint 2010, all results, no matter which type they were, looked quite the same. Take a look at the following screenshot showing a results page from FAST for SharePoint 2010:

The results are dull looking, can't be told apart, and in order to find what you are looking for, you have to scan the results up and down with your eyes and zero in on your desired result.

Now let's look at how results are displayed in SharePoint 2013:

What a difference! The page looks much more alive and vibrant, with easy distinguishing of different result types and a whole new hover panel, which provides information about the hovered item and is completely customizable.

Display templates

Search, and its related web parts, makes heavy use of display templates instead of plain old XSLT ( Extensible Stylesheet Language Transformations ). Display templates are basically snippets of HTML and JavaScript, which control the appearance and behavior of search results. SharePoint ships with a bunch of display templates that we can use out of the box, but we can also create our own custom ones.

Similar to master pages, it is recommended to copy an existing display template that is close in nature to what we strive to achieve and start our customization from it. Customizing a display template can be done on any HTML editor, or if you choose, even Notepad. Once we upload the HTML template, SharePoint takes care of creating the companion JavaScript file all by itself.

If we tear apart the results page, we can distinguish four different layers of display templates:

The layers are as follows:

  • Filters layer : In the preceding screenshot they are highlighted with the green border on the left and numbered 1. This layer shows the new refinement panel area that is not limited to text alone, but also enables the use of UX elements such as sliders, sliders with graphs, and so on.
  • Control layer : In the preceding screenshot they are highlighted with the red border in the middle and numbered 2. This layer shows that not only results but also controls can be templated.
  • Item layer : In the preceding screenshot they are highlighted with the orange border in the middle and numbered 3. This layer shows that each result type can be templated to look unique. For example, in the screenshot we see how a site result (the first result), conversation results (next three results), and image result (last one) looks like. Each result type has its own display template.
  • Hover panel layer : In the preceding screenshot, they are highlighted with the blue border on the right and numbered 4. They are introduced in SharePoint 2013, the hover panel shows information on a hovered result. The extra information can be a preview of the document (using Office Web Apps), a bigger version of an image or just about anything we like, as we can template the hover panel just like any other layer.

Display templates are stored in a site's master page gallery under the Display templates folder.

Each one of these layers is controlled by display templates. But if design templates are the beauty, what are the brains? Well, that is result types.

Result types

Result types are the glue between design templates (UX—user experience) and the type of search result they template. You can think of result types as the brain behind the templating engine.

Using result types enables administrators to create display templates to be displayed based upon the type of content that is returned from the search engine. Each result type is defined by a rule and is bound to a result source. In addition, each result type is associated with a single display template.

Just like display templates, SharePoint ships with it a set of out of the box result types that match popular content. For example, SharePoint renders Word document results using the Item_Word.html display templates within any result source if the item matches the Microsoft Word type of content. However, if an item matches the PDF type of content, the result will be rendered using the Item_PDF.html display template.

Defining a result type is a process much like creating a query rule. We will create our first result type and display template towards the end of the article.

Both result types and display templates are used not only for search results, but also for other web parts as well, such as the Content Search Web Part.

Styling results in a Content Search Web Part

The Content Search Web Part (CSWP) comes in handy when we wish to show search-driven content to users quickly and without any interaction on their side.

When adding a CSWP we have two sections to set: Search Criteria and Display Templates . Each section has its unique settings, explained as follows:

  1. The search criteria section is equivalent to the result type. Using the Query Builder we tell the web part which result type it should get. The Query Builder enables us to either choose one of the built-in queries (latest documents, items related to current user, and so on) or build our own. In addition, we can set the scope of the search. It can either be the current site, current site collection, or a URL. For our example, we will set the query to be Documents(System) , meaning it searches for the latest documents, and the scope to Current site collection :

  2. Next, we set the display template for the control holding the results. This is equivalent to the Control layer we mentioned earlier. The CSWP provides three control templates: List , List with Paging , and Slideshow . The control templates change the way the container of the items looks. To compare the different templates, take a look at how the container looks when the List template is chosen:

  3. And the following screenshot displays how the exact same list looks when the Slideshow template is chosen:

    Since our content is not images, rendering the control as Slideshow makes no sense.

  4. Last but not least, we set the Item display template. As usual, SharePoint comes with a set of built-in item templates, each designated for different item types. By default, the Picture on left, 3 lines on right item display template is selected. By looking at the preceding screenshot we can see it's not right for our results. Since we are searching for documents, we don't have a picture representing them so the left area looks quite dull. If we change the Item display template to Two lines we will get a much more suitable result:

Display templates allow us to change the look of our results instantly. While playing around with the out-of-the-box display templates is fun, extending them is even better. If you look at the Two lines template that we chose for the CSWP, it seems kind of empty. All we have is the document type, represented by an icon, and the name of the document. Let's extend this display template and add the last modified date and the author of the document to the display.

Creating a custom display template

As we mentioned earlier, the best way to extend a display template is to copy and paste a template that is close in nature to what we wish to achieve, and customize it. So, as we wish to extend the Two lines template, open SharePoint Designer, navigate to Master Page Gallery | Display Templates | Content Web Parts of the site you previously added the CSWP, and copy and paste the Item_TwoLines.html file into the same folder. Rename the newly created file to Item_TwoLinesWithExtraInfo.html. As soon as you save the new filename, refresh the folder. You'll notice that SharePoint automatically created a new file named Item_TwoLinesWithExtraInfo.js. The combination of the HTML and JavaScript file is what makes the magic of display templates come to life. Edit the Item_TwoLinesWithExtraInfo.html file, and change its title to Two Lines with Extra Info.

Getting the new properties

The first code block we should discuss is the CustomDocumentProperties block. Let's examine what it holds between its tags:

<mso:CustomDocumentProperties> <mso:TemplateHidden msdt:dt="string">0</mso:TemplateHidden> <mso:ManagedPropertyMapping msdt:dt="string">'Link URL'{Link URL}:'Path','Line 1'…</mso:ManagedPropertyMapping> <mso:MasterPageDescription msdt:dt="string">This Item Display Template will show a small thumbnail…</mso:MasterPageDescription> <mso:ContentTypeId msdt:dt="string">0x0101002039C03B61C64EC4A04F5361F385106603</ mso:ContentTypeId> <mso:TargetControlType msdt:dt="string">;#Content Web Parts;#</mso:TargetControlType> <mso:HtmlDesignAssociated msdt:dt="string">1</mso:HtmlDesignAssociated> <mso:HtmlDesignConversionSucceeded msdt:dt="string">True</mso:HtmlDesignConversionSucceeded> <mso:HtmlDesignStatusAndPreview msdt:dt="string"> catalogs/masterpage/Display%20Templates/Content%20Web%20Parts/Item_ TwoLinesWithExtraInfo.html, Conversion successful.</mso:HtmlDesignStatusAndPreview> </mso:CustomDocumentProperties>

The most important properties from this block are:

  • ManagedPropertyMapping : This property holds all the managed properties that our display template will have access to. The properties are organized in the key:value format. For example, if we wish to make use of the Author property, we will declare it as 'Author':'Author'. The value can be a list of managed properties, so if the first one is null, the mapping will be done using the second one, and so on.
  • ContentTypeId : This property sets the content type of the display template. The specific value recognizes the file as a display template.
  • TargetControlType : This property sets the target of the display template. In our example it is set to Content Web Parts , which means the search content web part and any other related search content web part. Other possible values are SearchBox , SearchHoverPanel , SearchResults , and so on.

Since we wish to display the author and the last modified date of the document, let's add these two managed properties to the ManagedPropertyMapping property. Add the following snippet in the beginning of the property, as follows:

<mso:ManagedPropertyMapping msdt:dt="string">'Author:'Author','LastModified':
'LastModifiedTime',… </mso:ManagedPropertyMapping>

We mapped the Author managed property to the Author key, and the LastModifiedTime managed property to the LastModified key. Next, we will discuss how to actually use the new properties.

Getting the values of the new properties

Using the newly added properties is done using plain old JavaScript.

  1. Scroll down a bit until you see the following opening div statement:

    <div id="TwoLines">

  2. The div tag begins with what seems to be a comment markup (<!--), but if you look closer you should recognize that it is actually JavaScript. By using built-in methods and client object model code, display templates can get any information out of SharePoint, and of the outside world. The getItemValue method is in charge of getting content back based on a given managed property. That means if we wish to get the author of a result, and we set the key to the managed property to be Author, the following line of code will get it:

    var author = $getItemValue(ctx,"Author");

  3. The same goes for the last modified date. We used the key LastModified for the managed property, and hence the following line of code will be used:

    var last = $getItemValue(ctx,"LastModified");

  4. Add these two lines just above the closing comment statement markup (_#-->).

Remember that each result is rendered using this display template, so the author and the last variables are unique for that one item that is being rendered.

Displaying the new properties

The last part of the template comes right after the closing comment statement from the previous section. You can see plain old regular HTML at this point, starting with the following line:

<div class="cbs-Item" id="_#= containerId
=#_" data-displaytemplate="Item2Lines">

But if you look close enough you might notice something is weird with the id property. It has an unusual suffix and prefix. This suffix and prefix are the template placeholders. Whatever value is between these two will get replaced at runtime with the value of its JavaScript variable.

Under the closing div tag of _#= line2Id =#_, add the following snippet:

<div class="cbs-Line2 ms-noWrap"><b>Author:
</b>_#= author =#_</div> <div class="cbs-Line2 ms-noWrap"><b>Last Modified: </b>_#= last =#_</div>

Author and LastModified are two variables we created in the previous section, and now using the template placeholders we will display them to the users.

Save the new template, and navigate to the site you saved the new template on, which should be the same site to which you added the CSWP earlier as well. Edit the properties of the CSWP and change its display template to our new Two Lines with Extra Info custom display template . Click on OK and you should get a result similar to the following screenshot:

Modifying the default image display template

As we mentioned earlier, the best way to modify a display template is to pick up an out of the box one and modify it. In order to change the image template hover panel, we have to first edit the image display template itself and point it to the new hover panel template we will be creating. To modify the default image display template follow these steps:

  1. Launch SharePoint Designer 2013 and open the search center site.
  2. Navigate to Master Page Gallery | Display Templates | Search folder , and locate the Item_Picture.html file.
  3. Once located, copy and paste it in the same folder.
  4. Rename the new file to Item_Console_Picture.html. Click on the file and under Customizations click on Edit file .
  5. Change the title of the new template to Console Picture Item.
  6. Under the body tag, locate the declaration of the hoverUrl parameter and change it as follows:

    var hoverUrl = "~sitecollection/_catalogs/masterpage/
    Display Templates/Search/Item_Console_Picture_HoverPanel.js";

  7. Save the file and navigate back to the Search folder.

Now that we have a new image display template, we need to create the new hover panel display template that we had specified for it. To create the new hover panel display template follow these steps:

  1. Locate the Item_Picture_HoverPanel.html file, copy and paste it in the same folder, and rename it to Item_Console_Picture_HoverPanel.html.
  2. Edit the file and add the Keywords managed property to the ManagedPropertyMapping property, just like we did in the previous example. The property should look like the following code:

    <mso:ManagedPropertyMapping msdt:dt="string">
    'Keywords':'Keywords','Title'… </mso:ManagedPropertyMapping>

  3. Under the div tag in Item_Picture_HoverPanel.html, locate the JavaScript section (that begins with <!--#_) and before its closing element add the following line of code:

    var keywords = $getItemValue(ctx, "Keywords");

    This will get the content of the Keywords managed property.

  4. To display the value of the keywords managed property to the user, add the following lines of code under the span whose ID is:

    _#= $htmlEncode(id + HP.ids.dimensions) =#_:<br/> <b>Keywords: </b> _#= keywords =#_

  5. Save the file.

We are done with creating the templates, so now it's time to create the result type.

Creating the result type

To create the result type that will match the new display template we created, follow these steps:

  1. In your search center, navigate to Site Settings and click on Result Types under the Search section.
  2. In the Manage Result Types page, click on New Result Type . Give the new result type a name such as Console Picture Type .
  3. For the source select the Video Games Result source (reminder: we only wish to have the new display template shown in our search vertical).
  4. Click on Show more conditions on the left, and choose Path as the property. For the operator select Contains any of and <your site url>/VideoGamesImages/ as the value. In our example, the value would be
  5. For the display type, choose Console Picture Item . This is the display template we created in the previous section. Save the result type. Once completed, your settings should look as shown in the following screenshot:

We are now finished with the new result type and display template. Go ahead and perform a search using our Video Games search vertical.

Hover over any image result and our new hover panel display template will be shown in all its glory as shown in the following screenshot:


This article was all about prettifying items. We learned about result types and display templates, what the different layers of display templates are, and how to style results in search-related web parts.

We finished the article off by creating two new display templates: an item display template based on the Two lines out of the box template and a new hover panel display template for the image display template.

Display templates are a powerful feature, and among its popular usages are adding a person's latest status updates whenever someone hovers over their result in the people search, showing the user's latest tweets based on their username, and so on. All of this can be achieved using display templates and a bit of JavaScript client object model.

Resources for Article :

Further resources on this subject:

You've been reading an excerpt of:

Learning Search-driven Application Development with SharePoint 2013

Explore Title