Creating custom display templates

Custom Display Templates / SharePoint 2013

Recently I have been working with display templates and the Content by Search web part on a customer engagement. I thought I would write up some ‘how to’ type material for you all in case you are having your first experience with them.

This blog article walks you through the following scenario:

  1. I have a heavily branded SharePoint 2013 Intranet for my customer Contoso. They have a number of news articles that they want to aggregate onto the landing page.

Display Templates

If you are here, then you most likely know what a display template is, and as SharePoint 2013 has been around for a while now there is already a lot of great content out there explaining what they do, so I won’t try and write a new take on them. My only add about customising Display Templates is the syntax may be a little confusing at first, but when I compare the experience of writing XSLT (in past versions of SP) to the experience of creating a custom display template, there is clearly a winner, and the winner is Display Templates by a long way J

Below you can see a screenshot of what we want to create for our first scenario. It is a web part (content by search) that displays the first four employee stories:

The first thing to point out here is that the end result (e.g. what you are seeing in the screenshot above) is actually composed of two separate display templates. We have a control template, and an item template.

Look at the screenshot, forgetting SharePoint for a brief moment and think about which HTML element would most suit a bunch of items that you want to look the same. Yep, the <ul> element. (That wasn’t a test question J, but +10 points if you got it right!)

Our ‘Control’ display template is going to contain our <ul> element and any other code that we need, think custom JavaScript or CSS classes. The control template is your opportunity to control how the group of results is going to be displayed; not the individual items themselves.

Moving on to the ‘item’ template. As we are going to use the unordered list <ul> element for the collection of items, we need to use the list item <li> element for each of the individual news stories. The ‘Item’ display template is the markup, JavaScript and CSS that is applied to each item within the list.

Types of Display Template

Whilst we are looking at two different types of display template, we should also look at what else is available to us as there are actually four different types of Display Template:

  1. Control Display Templates

  2. Group Display Templates

  3. Item Display Templates

  4. Filter Display Templates

Display templates are associated with content types in the Master Page gallery. When a .html document (e.g. your display template) is uploaded to the Master Page Gallery; the same event receivers that are responsible for creating .aspx and .master versions of design files work to create the .js version (HTMLDesignEventReceiver).


So far we have established that news article items are going to be returned as list items (<li>). Each <li> contains an image, which is also going to link to the news item page, some introduction text, and a label for the author; so in terms of HTML we are looking at:

<a href=”<some url in here>”>
<img src=”<some url in here>” />
<!—- next item -->

The content.

The first thing that we need before we start developing our display templates is the content!

Below is a partial screenshot of a ‘news article’ page:

 Firstly, as we are going to be using the Content By Search web part, we need to make sure that our content has been crawled! Otherwise, this is going to be a short article!

Secondly, we are going to be mapping news article properties in the web part’s configuration. Our news article contains images, headings, bylines, author name, etc, so we can really choose what properties we want to be displayed. So the second check there is to make sure that the properties are mapped.

In this walkthrough, I have already crawled my content, and checked that the crawl has picked up and more importantly mapped properties for my news article.


Quick sense check:

  1. We have a number of news article pages that are all ‘ContosoNewsPage’ content types.

  2. They have been crawled by our SSA.

  3. The crawled properties of our news articles are mapped.

We are ready to create our display templates, and then add & configure the content by search web part.

Reinventing the wheel.

If we take a look at the display templates that are provided out of the box with SharePoint, you can see that we have most scenarios covered. By that, I mean that in this example, we have a list of items that are being rendered with an image, and essentially two lines of text. This means that we can make the most of what the product group have given us, and take a copy of the closest display template that matches what we are trying to do.

In this instance, I am going to take a copy of the ‘List’ control display template, and the ‘Picture on top, 3 lines on bottom’ item display template. This gives us a good starting point.


Locating display templates.

If you go to:

  1. Open Site Settings, and then click on the Master pages and page layouts link.

  2. Open the Display Templates document library, and then open the Content Web Parts document library.

You should see a bunch of .html and .js files. We want to download a copy of the two display templates that we intend to update to display the content how we want it to :)

Therefore, go ahead and download the Control_List.html and Item_Picture3Lines.html files.

Note: do not download the .js equivalent files. J

Updating Control_List.html

We’re going to take a perfectly suitable display template, and tweak it a little so that it has our own markup. If you open the Control_List.html file in your preferred ISE; then take a look at the <head> section:

You’ll notice pretty much straight away that when you are editing the web part’s properties, you are seeing the <title> element as the title property of the display template. So change this to (whatever you like) ‘Employee Story List’ in my case.

You should also notice the following:

<mso:MasterPageDescription msdt:dt=”string”>This is the default Control Display Template…</MasterPageDescription>

This property contains the information that is displayed as the description of the Control Display template. Go ahead and enter some user friendly description of what this template will do.

We don’t need to change any of the other properties in the <head> section, so scroll further down to about line 50…

In the screenshot above you can see there is some HTML markup (line 60 & 64) where we are creating our <ul> item. In between the opening and closing <ul> we are going to pass in our results from the Content By Search web parts query in the form of <li> that our item display template will control.

The other interesting piece here, which you don’t need to change is the var ListRenderRenderWrapper. Within this, we are writing out our <li> items.

The only customisation I have had to make to the Control Display Template is to add in the class=”fullWidth containsImage” so that I can style the results as per my responsive CSS classes.

Once I have finished editing this file I will save it as Control_EmployeeStory.html.

The final stage is to import this into SharePoint:

  1. Open Site Settings, and then click on the Master pages and page layouts link.

  2. Open the Display Templates document library, and then open the Content Web Parts document library.

  3. In the ribbon, click Files, then Upload Document.

  4. Browse to the location where you have saved the Control_EmployeeStory,html file and click OK.

You will now notice that there is a corresponding .js file that has been created for you in the background:

Next we need to go through the same process and edit our copy of Item_Picture3Lines.html

Updating Item_Picture3Lines.html

Take a look at the <head> section of this display template

You’ll notice that it differs slightly from the control display template. We still have the <title> field that we need to change (this is what we are going to see when we edit the content by search web part properties); but in addition to this we now have the following section to take a look at:

 This is where we are able to map our default properties to variables; take a look:

<mso:ManagedPropertyMapping msdt:dt=”string”>
‘Picture URL’{Picture URL}:’PublishingImage’

And then look at the UI of the web part:

These mapped properties indicate which values will be passed into our display template by default; we can change them, but for now we’ll leave things as they are.

The next steps are the same as the control display template, we need to save the .html file and upload it into the Master pages and page layouts gallery.

Once you have finished, you can go ahead and define the search query that will return your content, and select the two new display templates that you just uploaded.

Your results may not look the same as mine as I have added some custom CSS to make it look how I wanted, and also to be responsive. 

Hope this helps you create some amazing display templates :)