How to Deploy Display Templates in SharePoint 2013

A few months ago I posted a question on an MSDN forum asking how to deploy display templates via feature. Several people had suggestions but John Ross provided many helpful comments that really made me think. Even now, I’m not 100% sure what the “best practice” is but hopefully I can lay out the options I’ve found and you can make the best decision for your situation.

SharePoint 2013 introduces a new way to transform your search results and provide a great user experience through the use of display templates. In SharePoint 2010 we had to use XSLT to customize that display. If you’ve ever tried XSLT you probably still have the battle scars to show it. The great thing about display templates is that you create them by leveraging skills that many developers already possess: HTML and JavaScript.

The most likely approach to creating display templates is to start with an existing display template HTML file and customize it. It’s not too difficult when you get the hang of the _#= (underscore pound equals) syntax. It’s very important to understand what happens when you edit that HTML file. When you click save SharePoint creates a JavaScript file and associates the two together. (FYI: The same thing happens when creating master pages using the design manager but HTML to MASTER file). When you select your display template in the content by search web part it is actually looking for the JavaScript file…not the HTML file.

The Dilemma

To deploy your display template you have to get that JavaScript file into SharePoint. So, how do you package this up and make it deployable? I’ve tried a couple different scenarios with Pros and Cons.

Method 1: Declarative

In this approach you use any tool to develop your display template in a development environment. When you’re done you copy the generated JavaScript file to your Visual Studio solution and deploy it using a file module. Do not deploy the HTML file.

Pros:

  • Display template remains ghosted (uncustomized) in future solution updates.

Cons:

  • Process of copying and pasting files is error prone.
  • HTML designer source remains in the development environment. So if changes need to be made to the display template after the development site has been blown away, you’ll be depressed. I’ve recommended copying the HTML file so the Visual Studio solution just to get it in source control. This protects you but it makes the copy/paste process even more tedious.

Example

The elements.xml file module needs to contain several properties for the display template. Below is an example of the minimum xml requirements I’ve found for a successful deployment.

<File Path="Display Templates\Custom_Item_Template.js" Type="GhostableInLibrary" Level="Published" ReplaceContent="TRUE" Url="Content Web Parts/Custom_Item_Template.js" >
  <Property Name="ContentTypeId" Value="0x0101002039C03B61C64EC4A04F5361F38510660500C3F5F262E5F0D1468E353B575444E8C9" />
  <Property Name="Title" Value="Custom Template" />
  <Property Name="TargetControlType" Value=";#Content Web Parts;#" />
  <Property Name="DisplayTemplateLevel" Value="Item" />
  <Property Name="ManagedPropertyMapping" Value="'Link URL'{Link URL}:'Path','Line 1'{Line 1}:'Title','Line 2'{Line 2}:'CommentsOWSMTXT','Line 3'{Line 3}:'PublishingPageContentOWSHTML','Line 4'{Line 4}:'DisplayTemplateJSIconUrlOWSURLH','Line 5'{Line 5}:'PublishingImage;PictureURL;PictureThumbnailURL','SecondaryFileExtension'" />
  <Property Name="TemplateHidden" Value="FALSE" />
</File>

Method 2: Declarative + Feature Receiver

Using this approach you deploy the HTML designer file to SharePoint declaratively using a file module. Unfortunately this process alone doesn’t create the all important JavaScript file. That’s where the feature receiver comes in. On feature activated, you grab the file and make a minor edit. This will force the Master Page item event receivers to fire and create the JavaScript file. Simple enough.

Pros:

  • Very simple to edit the design.
  • If you’re using Visual Studio and TFS, the HTML file will be saved to source control. This may seem like a minor benefit but it cannot be overlooked. You can always use this file to re-create the JavaScript file if necessary. There’s no handy tool to handle the reverse

Cons:

  • That minor edit will cause the HTML file to become unghosted (or customized). If the display template is used in multiple sites it will be very difficult to roll out changes.

What do I recommend?

As with so many SharePoint complications, the answer is “it depends.” If your display template is only used on a few sites, I would recommend using the Declarative + Feature Receiver. Otherwise, I’d recommend going purely declarative.

The Code

DisplayTemplatesDemo.zip

As always I hope this someone.

Updated 3/28/2013 to include code

18 thoughts on “How to Deploy Display Templates in SharePoint 2013

  1. Eric

    Would you be able to post your event receiver? Also, have you trying deploying to the “_layouts/” folder, so you have a single copy across sites?

    Reply
    1. LesterLester Post author

      Hi Eric. I’ll post the code a little later today. I don’t think the _layouts direction will work with the OOTB web parts. Only display templates that are in the site will appear in the web parts Display Template drop down. However, you may be able to export the web part and change the properties to point to a display template in the _layout folder. I’m just not sure.

      Reply
  2. Leo

    I guess the first (declarative) method is the recommended one. At least that is how Microsoft deploys the js-File originally

    They are delivered through the builtInFeature “SearchWebParts” and the declaration is found in “DisplayTemplateColumns.xml” just the way you showed it.

    Reply
  3. Uday Joshi

    Hi Lester
    I have observed that the .js file is created when we upload the HTML file as in the Method 2, but without using the event receiver for the edit and then we just click ‘Edit Properties’ from the ECB and click on ‘Save’ button without changing anything.

    Reply
    1. LesterLester Post author

      Yes. And that’s the reason I made this article. If you’re deploying several display templates, having the manually edit each one quickly becomes an annoyance.

      Reply
  4. Pingback: How to Deploy Display Templates in SharePoint 2013 | Share your knowledge

  5. Johannes Stock

    Hi Lester,
    great article Thanks! Your feature receiver code worked for me after i added the full path to the spfile.
    I think this comes from havig my site using a managed path.

    Heree’s the code snippet:

    var url = SPUtility.ConcatUrls(gallery.RootFolder.Url, “Display Templates/Search”);
    url = SPUtility.ConcatUrls(url, displayTemplate);
    url = SPUtility.ConcatUrls(web.Url, url);
    //get the file
    var fileOrFolder = web.GetFileOrFolderObject(url);

    Reply
  6. Daniel

    Lester, I have the same dilemma . I wonder if we can’t incorporate this into an App and use the new client side provisioning API . Although this does currently have limitations so as list definitions and Content Types ( see that “Vesa” blog post ).
    From what I have been reading we’re should be moving towards cloud ( office 365) friendly deployments even if it is on prem. Well that’s the theory! I will shortly compare your declarative approach with that.

    Reply
    1. LesterLester Post author

      I don’t think your App can push files into the host web. Still fuzzy on that. But I think the recommended approach in O365 is to use the design manager and add files directly. Using this approach you won’t have the dilemma I discussed.

      Reply
  7. Brian

    NOTE: Display Templates, like other assets in the Master Page Gallery, must be Published in order for everyone to see them. Once you have completed your edits, return to the Mater Page Gallery and Publish a Major Version of the files so that your users will be able to see them.

    Site Settings, Site Collection Administration, Go to top level site settings

    From Top Level site – Site Collection Admin – Search Result Types

    Link from within the first sentence at top for “crafting a display template in HTML.”

    Reply
  8. Craig

    I have used this code to deploy my display template HTML files.
    In debugger I can see that the event receiver finds the draft HTML items, checks them out, does an update and then publishes. But it does not create a JS file! The only way for me to create a JS file is to use SP Designer – check it out, edit it and save it. Then there is a new JS file. Then I can publish each of my HTML files. This is annoying enough, but every time I deploy my VS solution the JS file disappears completely and I have to edit all the HTML files again to get my JS files again.

    Reply
    1. LesterLester Post author

      I’m not sure what’s up with that. I’ve used this same code at least a dozen times and it always works for me. I wonder what happens when you turn off versioning, check-in/out, and approval.

      Reply
  9. Ahmed M. Gamil

    I’ve noticed something strange when I uploaded HTML display template files only and fired the event receiver afterwards it created a strange JS file. The newly created JS gave me an error “Out of Stack Space” at “ItemRenderWrapper” or something. This issue was fixed when I deployed both HTML and its corresponding JS file and fired the event receiver.

    Any explanation to this issue?

    Reply

Leave a Reply

Your email address will not be published. Required fields are marked *

You may use these HTML tags and attributes: <a href="" title=""> <abbr title=""> <acronym title=""> <b> <blockquote cite=""> <cite> <code> <del datetime=""> <em> <i> <q cite=""> <strike> <strong>