In SharePoint 2013 display templates are used with the content by search web part (CSWP) to format and style search results generated by the CSWP search query. Display templates control which managed properties are shown in the search results and how they appear in the web part. Each display template consists of two parts, the HTML version of the template that you can edit and a .js file SharePoint auto-generates for its use (never to be edited by you) when an HTML file is uploaded.
There are two types of display templates:
- Control Template: is rendered only once in the web part and contains HTML to structure the overall layout of how you want to present the search results. I.e. HTML for a heading, beginning and end of a list
- Item Template: is rendered one time for each item in the result set, i.e. for a results set containing five items, the template creates its HTML section five times
OHS Document Item Display Template
To see the code please view OHSDocItem_TwoLines, a text file containing the code. To use the template would need to change the file extension from txt to html.
Code Breakdown
The key here is to take a copy of one of SharePoint’s already created item templates that is close to what you are trying to create. In my case that was the Item_2Lines template. From their you need to make the necessary edits, which broken down for me are the following, with description underneath:
<title>
Edit the contents between the title tag to be what you want end users to see when selecting your display template, see Fig. 1.
<mso:ManagedPropertyMapping msdt:dt="string">'Link URL'{Link URL}:'Path','Line 1'{Line 1}:'Title','LastModifiedTime'{Line 2}:'LastModifiedTime', 'LastModifiedBy'{Line 3}:'LastModifiedBy','FileExtension','SecondaryFileExtension'</mso:ManagedPropertyMapping>
This one is key as to what information is going to be accessible for displaying items. Each one needs to be a managed property, specified in the ‘Search Schema’ for the correct search service application (SSA).
<mso:ContentTypeId msdt:dt="string">0x010100BEBD1B217F6D144191B58533C4577EAB1E</mso:ContentTypeId>
Within here is the content type ID for the content type your search query is returning. This can be found by going to your content type hub and clicking on the appropriate content type. You can then grab the ID from the URL displayed in the address bar.
<div id="OHSDocItem_TwoLines">
Initially will contain the file name portion of the one you copied, make it match yours.
var modified = $getItemValue(ctx, "LastModifiedTime");
Is an example of how to retrieve the contents of the managed property mapped via the first snipped of code above. This says to get the value stored in the item ‘LastModifiedTime’ using the current context, ctx (a variable SharePoint creates, handles, and makes available to you).
Usage
In my scenario I am using the CSWP to surface up OHS documents pertaining to a particular office, i.e. Atikokan, on a page within their office site. Our OHS documents are all of the content type “OHS Document”. Prior to utilizing the display template first the query returns back relevant results, in this case the query is ‘Return back items of the content type OHS Document where the tags metadata field contains the value Atikokan’, or in query form:
ContentTypeId:0x010100BEBD1B217F6D144191B58533C4577EAB1E* Tags:Atikokan
Fig. 1 shows the customization of the CSWP, where the query is done in an additional window by clicking ‘Change Query’. In this case we are using the ‘List with Paging’ control (a.k.a. the control template) which allows the user to scroll through results, 15 per page, by using the arrows. The item template is the one I created (see Making Your Display Template Accessible below). The property mappings are pulled directly from the display template as specified within the <mso:ManagedPropertyMapping msdt:dt=”string”> tag.
The result of the display template is shown in Fig. 2, where the managed property mappings correlate as follows:
- ‘Path’: Contains the URL to the item being displayed
- ‘Title’: Is the title from the document, which may be the same as the the file name. In our environment we’ve had to correct a few of these so that they are meaningful
- ‘LastModifiedTime’: Contains the date the file was last modified and makes up part of the 2nd line of the display template
- ‘LastModifiedBy’: Contains the person who last modified the document and makes up the second part of the 2nd line. This managed property I created includes a mapping to the crawled properties LastModifiedBy, ows_Modified_x0020_By, and ows_ModifiedBy.
As you can see in Fig. 2 this does not always contain a value, so there appears to still be a better crawled property (or perhaps ordering of crawled properties within my managed property) to be utilized. To handle this I have if conditions, seen as ‘comment sections’ in the code below which determines which code needs to be added for display. If the modified date is empty then nothing will get displayed and if modified date is not empty and the last modified person is not empty then ‘by’ is inserted along with the person who last modified the document. This prevents ‘by’ appearing without specifying an individual.
<!--#_
if(!modified.isEmpty)
{
_#-->
<div class="cbs-modified ms-noWrap" title="_#= $htmlEncode(modified.defaultValueRenderer(modified)) =#_" id="_#= modifiedId =#_">Last modified on _#= modified =#_
<!--#_
}
_#-->
<!--#_
if(!modified.isEmpty && !lastModifiedBy.isEmpty)
{
_#-->
by _#= lastModifiedBy =#_
<!--#_
}
_#-->
<!--#_
if(!modified.isEmpty)
{
_#-->
</div>
<!--#_
}
_#-->
Making Your Display Template Accessible
At first I tried to copy an existing template and discovered that copying an existing HTML file to my local machine and then editing it, followed by copying it back did not work for me. What I had to do instead of copying it back through Windows Explorer I needed to navigate to ~sitecollection/_catalogs/masterpage and then drill down into ‘Display Templates -> Content Web Parts’. Then to add my newly created display template from the ribbon I navigated to ‘FILES -> New Document -> Item Display Template’, left clicking on ‘Item Display Template’ as that is the type I have created.
I then chose my display template HTML file *Item_*.html (Fill the * to get actual template name as this is my naming convention), added appropriate version comments, then clicked ‘OK’. I left the default properties on the document, as it appeared to pull everything correctly from the file. After reading it over I clicked ‘Save’. Refreshing the page by clicking ‘Content Web Parts’ and now see two additional files:
*Item_*.html (That I uploaded)
*Item_*.js (That was generated as expected)
Once this process is done you should be able to edit the properties of the CSWP and see the newly added display template under the drop down list ‘Item’ for display templates. The name will be as you described it using the HTML title attribute in the HTML file.
For an introduction to display templates with screenshots, that got me started, you can see an article by Matthew McDermott entitled Introduction to SharePoint 2013 Display Templates.