MJ's Sharepoint Blog: Understand & Customize Display Templates

Display templates are new in sharepoint 2013 replacing XSLT in 2010 which will be used to customize the UI/display of the webparts. Like, we had item.xsl and control.xsl back then, its same strategy in 2013 as well. Entire UI code for a webpart is split into 2 different files, Control and item template. Control template will have the markup that creates the base look/container/header section for the webpart where as item template will have the markup defined for each result/item displayed.

For every display template(item/control) file(.html) uploaded to the master page gallery, a respective js file will be generated if no syntax errors found. Publishing features at site collection need to be activated so sharepoint could generate those files.

To start with creating a custom item template, copy any of the OOTB template and start following its pattern and conventions. I have explained few notations to make it easy for you and myself.

Ensure all the changes are written inside the first div under the body of the template. Sharepoint reads only the markup which is inside the first div(excluding div element itself) while applying the item template to each item in the webpart.

I have copied part of the code from item_picture3lines.html for better explanation. Here, the first div is with id=item_picture3lines. Id of the div can be changed but not the div element itself.

<body>
<div id="Item_Picture3Lines" >


<div class="cbs-picture3LinesContainer" style="font-size:11px;" id="_#= containerId =#_" data-displaytemplate="_#= $htmlEncode(dataDisplayTemplateTitle) =#_">
...
…
</div>
</div> </body>

Scripting

Javascript/jquery can be written by wrapping it with  without explicit script tags. So it's going to look like,

External js file can be included by using the function,includeScript. First parameter is always this.url

$includeScript(this.url, "~sitecollection/_layouts/15/reputation.js");

Similarly external CSS can be referenced using $includeCSS(this.url, "~sitecollection/site library/custom.css");

Read here on how to run the scripts after display template or complete DOM render($(document).ready())

Property Mappings

To add new lines in content search webpart or do property/managed metadata mapping in display template,

look for mso:managedPropertyMapping in item template which is responsible for mapping the columns to the variables in the display template and to show in the toolpart.

<mso:ManagedPropertyMapping msdt:dt="string">'Link URL'{Link URL}:'Path','Line 1'{Line 1}:'Title','Line 2'{Line 2}:'Author','Line 3'{Line 3}:'ModifiedOWSDATE','FileExtension'</mso:ManagedPropertyMapping>

'Link URL'{Link URL}:'Path' defines single mapping for a managed metadata.

'Link URL'{Link URL}:'Path' - first token represents the label of the property displayed in the toolpart under property mappings

'Link URL'{Link URL}:'Path' - second token represents the display name of the variable reference to the actual managed metadata property. This variable will be used in the display template to access the value.

'Link URL'{Link URL}:'Path' - last token is the actual name of the managed metadata that is used in display template. This is not the display name of the column but the name of the managed metadata property mapped to the crawled property in search schema.

In case of mapping multiple metadata properties to a single display template property variable, follow the below syntax

'Link URL'{Link URL}:'Path;Url'

When no mapping required but need to access the value of managed metadata inside display template just add it in single quotes separated by comma like FileExtension is added.

Context

Sharepoint by default loads the context(ctx) as part of display template that can be used to access many of the contextual properties when customizing display templates.

Access the value of a mapped property by using getitemValue.

Var value = $getItemValue(ctx, "Line 2");

$getItemValue takes the display name of the property(second token in parenthesis) as the second parameter. This way code is generic and it still works even if the property mapping is changed in webpart configuration. Also, if there are managed metadata properties that need to be used(like listItemID,ItemID) that don’t need to be listed in the property mappings, the value of it can be fetched by directly passing the manage metadata property name as per search schema.

The above line of code fetches Author value as {Line 2} is mapped to Author in the display template. Below code also fetches the same value,

Var authorVal = $getItemValue(ctx, "Author");

Few contextual properties which can be fetched from context,

ctx.CurrentItem.ListItemID

ctx.CurrentItem.SPSiteUrl

To retrieve the current item index or current row number use the property CurrentItemIdx from ctx object.

Var currentItemIndex = ctx.CurrentItemIdx;

Get the row count or total number of rows with,

Ctx.CurrentGroup.RowCount

Row count can be used in the logic when to apply alternate css/styles to the rows, where as row id to display any header section(table header) for the entire webpart. Header section can be added to control display template but if you don’t want to change 2 different files, just check for currentitemidx=1 and add header section markup in the item template itself. Note that these properties wont work in control display template.

To find if the results are empty inside control display template, I checked for DOM length being empty for div.ms-srch-result-noResults. Thought of using if (ctx.ClientControl.get_shouldShowNoResultMessage()) but did not work as expected. Yet to find a better approach.

Get the unique id by using ctx.ClientControl.get_nextUniqueId();

Access values in markup

Display value of the managed metadata property or a variable as part of the markup. Here authorVal is the variable in the above script having the value of the managed metadata property, Author.

<span>_#= authorVal =#_</span>

MJ's Sharepoint Blog

Thursday, May 29, 2014

Understand & Customize Display Templates

1 comment:

Followers