Display Template Series
In my previous post Brief Introduction into Display Templates I gave an overview of what a Display Template is. In this post I hope to delve a little deeper and show how they are used with Content Search WebParts.
When you add a Content Search WebPart or a Search Result WebPart when you configure the Web Part, you have to select a control and an item display template.
A Control Template is used to show how the results are presented, an HTML structure of the overall layout. The surrounding area that will contain all items returned. For example it could be the heading and footer. The control template is only rendered once within the WebPart.
An Item Template provides the HTML display for an item in the search results. This template will be called for each item in the result set. This allows you to define the layout of the item.
So when the WebPart uses them together it creates a rendered piece of HTML for the webpart.
A display template structure is made up of four main sections. Title, Header properties, Script Block and a DIV block.
Title
Very simply this is the display name that is found in the Display Template sections of the WebPart edit pane.
<title> My Display Name </title>
Header Properties
Following on from the title tag, there is a set of custom elements which provide information about the display template to SharePoint. These elements are surrounded by the following XML markup:
<!--[if gte mso 9]><xml>
<mso:CustomDocumentProperties>
…
</mso:CustomDocumentProperties>
</xml><![endif]-->
An example of an element would be;
<mso:TemplateHidden msdt:dt="string">0</mso:TemplateHidden>
<mso:MasterPageDescription msdt:dt="string">Displays a result tailored for a picture.</mso:MasterPageDescription>
The different properties and descriptions are described here (Taken directly from the Microsoft Website):
| Property |
Description |
| TemplateHidden |
Boolean value that indicates whether to hide the display template from the list of available templates in the Web Part. This value can be changed in the display template file properties. |
| ManagedPropertyMapping |
Maps fields exposed by search result items into properties available for JavaScript. Used only in item templates. |
| MasterpageDescription |
Provides a friendly description of the display template. This is shown to users in the SharePoint editing environment. This value can be changed in the display template file properties. |
| ContentTypeId |
The ID of the content type associated with the display template |
| TargetControlType |
Indicates the context in which the display template is used. This value can be changed in the display template file properties. |
| HtmlDesignAssociated |
Boolean value that indicates whether a display template HTML file has a .js file associated with it. |
| HtmlDesignConversionSucceeded |
Indicates whether the conversion process was successful. This value is automatically added to the file by SharePoint, and is used only in custom display templates. |
| HtmlDesignStatusAndPreview |
Contains the URL to the HTML file and the text for the Status column (either Conversion successful or Warnings and Errors). This value is automatically added to the file by SharePoint, and is used only in custom display templates. |
Script block
The script block is an area where you can add links to include internal, external JavaScript of CSS. You can use SharePoint tokens such as ~sitecollection to obtain URLs. An example shown below:
<script>
$includeScript(this.url, <a href="http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js">http://ajax.googleapis.com/ajax/libs/jquery/1.9.1/jquery.min.js</a>);
$includeCSS(this.url, "style library/Slider/css/MySearchWebPartStyle.css");
</script>
DIV block
The final part is a DIV block with an ID that matches the name of the HTML file. All HTML and code that you want the display template to use must be written within this DIV tag. Please note that this DIV tag is not rendered on the webpage at runtime. As I stated in previous blog, JavaScript code sits within comment blocks that start with <!–#_ and ends with _#–>. HTML sits outside these blocks. You can also uses these blocks control the HTML with conditional statements. Inside HTML attributes that are making script calls or using JavaScript variables need to start with _#= and end with =#_ comment blocks.
Example below taken from the Control_List.html file.
<div id="Control_List">
<!--#_
if (!$isNull(ctx.ClientControl) &&
!$isNull(ctx.ClientControl.shouldRenderControl) &&
!ctx.ClientControl.shouldRenderControl())
{
return "";
}
ctx.ListDataJSONGroupsKey = "ResultTables";
var $noResults = Srch.ContentBySearch.getControlTemplateEncodedNoResultsMessage(ctx.ClientControl);
var noResultsClassName = "ms-srch-result-noResults";
var ListRenderRenderWrapper = function(itemRenderResult, inCtx, tpl)
{
var iStr = [];
iStr.push('<li>');
iStr.push(itemRenderResult);
iStr.push('</li>');
return iStr.join('');
}
ctx['ItemRenderWrapper'] = ListRenderRenderWrapper;
_#-->
<ul class="cbs-List">
_#= ctx.RenderGroups(ctx) =#_
</ul>
<!--#_
if (ctx.ClientControl.get_shouldShowNoResultMessage())
{
_#-->
<div class="_#= noResultsClassName =#_">_#= $noResults =#_</div>
<!--#_
}
_#-->
</div>
You can use jQuery within your display templates, you must include the jQuery library in your Script Block. Also because jQuery is used to using the # symbol, which is also required in the templates, to reference an ID Selector using jquery it is recommend to use the following code;
var containerQueryId = ‘#’ + ‘_#= containerId =#_’;
$(‘_#= containerQueryId =#_’);
Display Template for Content Search WebPart.
When creating a Display Template it is recommend to copy an existing HTML display template that is similar to the one you wish to create. Once you have copied it and renamed, and reconfigured it, and saved it back to the Master Page Gallery, you will find a corresponding .js file automatically created for you.
By browsing to your publishing site, in the upper right corner of the page, choose Settings, and then choose Design Manager.
In Design Manager, in the left panel area, choose Edit Display Templtes. Your HTML file will now appear with a Status column that will either show “Warnings and Errors” or “Conversion successful”. Please note that Approval Status is set to “Draft” and you need to publish any files added to the Master Page Gallery from within the Master Page Gallery. 
Once you have converted the template successfully, but going to your web page with eth Content Search Web Part on, when editing you will now see your new template in the corresponding Display Template Control or item.
SharePoint and other geeky stuff 