The Anatomy of SharePoint 2013 Display Templates

SharePoint 2013 Display Templates, used in Search Results, Content Search Web Part and other search driven Web Parts to establish the visualization of the displayed data, are a combination of an HTML file and a JavaScript file. In order to create your own Display Template, you only need to modify the HTML file and let SharePoint handle the .js conversion. You can add your own JavaScript logic by referring to your own separate .js file in the HTML file.

The starting point is to copy one of the existing Display Template HTML files. Naturally, you want to start with one that is as close to your destined form as possible, so you can either try the existing ones out or check out the MSDN Display Template Reference.

As you can see in the reference (if you opened it), there are two basic types of Display Templates (Item and Control templates), plus the Hover template for the search results. As for the Control and Item templates, they are a loose pair. The Control template controls the basic structure where the data items will be injected, e.g. forming a list structure where the <li> element will be the repetitive element, diplaying data according to the selected Item template.

Disptemp1

SharePoint 2013 Display Templates - Control

SharePoint 2013 Display Templates Control

The actual Display Template files contain a bundle of HTML and JavaScript and jQuery.

First of all, the <head>

Both Control and Item Display Templates contain their basic information, like the Title and the Description in the head section of the HTML file.

Controlhead

The Item template also introduces the managed propert mappings used to retrieve the item metadata in the head section.

Itemprops

You can add Property Mappings and modify them, you can set default fields for data value retrieval or leave them empty.

Your own script or CSS

If you want to reference your own script or CSS style file, you can do that using the $includeScript or $includeCSS functions inside the <script> element in the body section, e.g.:

Include

Item Display Template Variables

In the Item Display Template, you need to set the variables, the mapped properties before you can use them in HTML. This is done in the code section inside the body:

Itemcode

Item Display Template HTML

Then, you can edit the HTML to your liking, e.g.

Itemhtml

Control Template Script and HTML

Control Templates contain a whole lot of jQuery & JavaScript to e.g. provide paging, and simply to provide the results. I did not find a reason to meddle with that, for now, but that can be customized as well.

The HTML structure is a bit scattered in the midst of the code, but you can find the element tags such as the <ul> start tag and add your own custom HTML within, e.g.

Controlhtml

to provide headers for the item info.

With a little bit of CSS…

…the template with some custom data could look like this:

Datatable

As for the deployment of these files?

You have two options:

1) Use the Design Manager. Map the -catalogs/masterpage gallery as a network drive, or use SharePoint Designer 2013 to work with the files. Once you have modified your Display Templates, upload them (the HTML files) and the possible support CSS and own script files to the MasterPage Gallery (select correct folder by intended usage, basically the same one you copied the file from). Check in Design Manager that the .js creation went ok.

2) Use VisualStudio2012. Create a SharePoint solution to deploy the files via a feature. Notes on this in How to Deploy Display Templates via SharePoint feature.

Sanna was a speaker at the ESPC 2013. Check out Bordering.net  for more insightfull blogs from Sanna!

For more SharePoint content from Geoff and other SharePoint specialists check out our resource centre!

Share this on...

Rate this Post:

Share: