Protiviti / SharePoint Blog

SharePoint Blog

October 05
SharePoint 2013 Display Templates Explained

​​Download the Starter Templates

Content Search Web Part (CSWP) DISPLAY TEMPLATES

With the push towards search related data using the Content Search Web Parts – you’ll quickly learn that this is valuable knowledge to be able to manipulate the HTML output as you need – just as we did with item styles for Content Query Web Parts prior to Microsoft introducing the CSWP.

The above ‘STARTER’ display template (sp2013-display-template-starter.txt) is an out of the box display template that I've cleaned up. I removed things that were unnecessary for every situation – to give us a clean slate to work with and so we don’t have to sift through the messy code to get to where we need.

So let’s get started creating a display template:

  1. Open your site in SharePoint Designer 2013 – and navigate to the _catalogs folder:
  2. From there you will navigate to the masterpage > Display Templates > Content Web Parts folder
  3. From the ribbon click on FILE > HTML
  4. Rename the file to what you want – but make sure you PRECEDE the name with ‘item_’ like so:
  5. Right click the file – check out – then right click it again and EDIT in Advanced mode
  6. Copy the contents of the sp2013-display-template-starter.txt and replace the entire contents of your new HTML file with this
  7. First thing you’ll want to do is FIND AND REPLACE every instance of the word ‘Starter’ and replace it with the name you want the display template to be (no spaces – the TITLE at the very top of the HTML can have spaces so if you want to add spaces to that you can for display purposes – but for consistency I just leave it without)
  8. At this point let’s save – and then go back to the folder where the display template resides – right click the file and CHECK IN > PUBLISH MAJOR VERSION – then refresh to see the newly created javascript file that SharePoint creates that does all the ‘magic’ behind the scenes

That’s it for a really quick example of how to create a display template…the process at least. If you were to go to a page and add a CSWP and edit the web part you’d see the display template as an option to choose – this one we created from the starter without changing anything gives you a TITLE that links to a URL (default is back to the item being rolled up) and a description (if the item being rolled up has a description field and has data)

Just like in a CQWP we can change the fields that are used for each field – so if your description field isn’t called Description – you can change that by clicking ‘Change the mapping of managed properties for the fields in the item Display Template’ under PROPERTY MAPPINGS


As you can see there are only 3 fields being used in the STARTER template. Here’s how you add more.

In your SharePoint display template this is where you add in the fields you want to capture the values of

<mso:ManagedPropertyMapping msdt:dt="string">...</mso:ManagedPropertyMapping>

You’ll see the 3 fields already in there from the starter -  like ‘Desc’{Description Label}:’Description’ using this syntax.

‘property name'{property display name}:’managed property’
  • property name
    is what you use in the script area to get the value and store it in a variable
  • property display name
    is the property name that shows in the Web Part editing pane – you can see ‘Description Label’ as an example of this in the above Property Mappings screenshot
  • managed property
    is the managed property you want to get the value of – this can be a placeholder and then you can select the correct field in the webpart tool pane – or you can check the Search Schema to see what the mapped property is – see below example for image)

You will use the property name in your code to get the value of that field and store in a variable (the variable name can be anything you want it to be).

var description = $getItemValue(ctx, "Desc");
Now, in your HTML, you can use that variable value to render the value of that field. You call variables like so...
_#= description =#_
Here’s an example where I’ve added an image field:
I found the managed property name by going to my root site settings page and clicking on SEARCH SCHEMA under the Site Collection Administration section. I did a search for IMAGE and I saw that the Property Name was PublishingImage for the rollup image that I had attached to one of my page layouts.

Then I stored its variable

Then render it in the HTML. The image variable stores the URL of the image – so you’ll build out the img tag and use the variable ‘image’ as the src=. The alt tag I just put the title of the item being rolled up. The alt tags on images are for 508 compliance – for screenreaders – and is required for all img tags.
Now this is a good time to explain what <!--#_   _#--> is.
Any javascript code is surrounded by these unique comments to tell the external js file that this is javascript and not just plain HTML.
If you strip that away you’ll see that it’s just a simple if statement that is evaluating whether the image field is empty or not and then renders the image if it is NOT empty.
<img src="_#= image =#_" alt="_#= title =#_">
The highlighted exclamation denotes NOT – so it’s saying if the image variable is NOT empty then render what is between the brackets.
As you can see now there is a field for image in the web part tool pane.
You can also do if statements with an else statement after to do if something is true then do this else do something else.

Here I’ve marked out the unique comments so you can see the simplicity of the code.

One thing I discovered recently is that publishing html or rich HTML fields need to be told to render the HTML and not just spit it out as text. So like in item styles where we have to handle those by setting – disable-output-escaping=’yes’ we render the variable so...
_#= STSHtmlDecode(description.value) =#_


Also above in the download section is a starter template for SEARCH RESULTS web parts (sp2013-search-dp-starter.txt) – it’s very very similar.

You’ll create the first HTML file in the SEARCH folder instead of the CONTENT WEB PARTS folder.

When adding more fields to the managedpropertymapping section however there’s no {property display name}  since the web part tool pane for the results web part doesn’t allow you to change the property mappings for the fields.

It’s a little tricky in this sense because you have to make sure the managed property is mapped to a crawled property and you’ll have to add the property name EXACTLY into the template for this to render the info you need.

So in these cases you will do for example...

'Rollup Image':'PublishingImage'

Since we knew the property name was PublishingImage for this image field.

There are tons of different ways to render the results and capture the data you need – this attached template is just a bare bones results display with title linked to the result items and description if there is one – there are things we can ‘steal’ and learn from that are in the other display templates OOTB – like how they do the hover with preview of the items in overlay…or how to render people results differently – I just wanted to give a starting point if we were using a search results webpart for custom data – to be controlled with URL query string and not necessarily a search results page per say…

My recommendation is to not remove any of the fields in the ManagedPropertyMapping as they are by default – but you can ADD custom fields if needed…

Those values that are there by default can be useful when you need them.

Also there are different ways you can get the values of the fields that are in that ManagedPropertyMapping

You can:

  1. Store value in variable like I’ve explained var modifieddate = $getItemValue(ctx, "LastModifiedTime"); then render the variable in your HTML like _#= modifieddate =#
  2. Store value in variable like this var modifieddate = ctx.CurrentItem.LastModifiedTime; then render the variable in your HTML like _#= modifieddate =#_
  3. Render the value in your HTML exactly like _#= ctx.CurrentItem.LastModifiedTime =#_





Quick Launch

© Protiviti 2020. All rights reserved.   |   Privacy Policy