Understanding Templated Client Rendering in SharePoint 2013 Beta

It’s another hot and rainy day here in Atlanta. It’s a good thing I have the beta to keep me inside!

The other day I wrote about the importance of JavaScript in SharePoint 2013. As I said, much of the server side rendering is replaced by client side script and while the old-school XSLT still works, you should consider it deprecated. To appreciate what I mean, consider the JSLink property which is now exposed via the object model and feature CAML for a wide variety of items including Fields, Content Types, and Views.

 

The JSLink property allows you to specify a JavaScript file that is responsible for rendering the item in the browser. As you can imagine, the JavaScript for a list view is pretty complicated. So, instead of jumping in tp the deep end of the pool today I will focus on customizing Search rendering for now. To follow along at home you will need to get search working and add some documents to a Team site and the same documents to a Publishing site. Alternatively, you can do this on Office 365.

Search Result Types

The improvements in Search in 2013 are incredible. Among the improvements is that SharePoint displays a hovercard when you mouse over a result.

If I had an Office Web Applications server installed, this hover card would also include an interactive thumbnail of the document itself so I could look at it without opening it!

The hovercard and the items listed in the search results are rendered via JavaScript. You can create rules to affect the display based on the items’ content types and even by field values. To see this, open a Team site in the browser, open the Site Settings page and click the Result Types link.

The Manage Result Types page lists all of the types with specific rendering. Each has rules that when true cause an item to use the given template and the order determines which rules get checked first. SharePoint applies the first match it finds. For the rest of this post I will use the Microsoft Word template.

The Microsoft Word result type specifies that

~sitecollection/_catalogs/masterpage/Display Templates/Search/Item_Word.js

will format the results for Word docs.


In my example I am using a document that has sections. The amazing new search indexer extracts that information from the document and displays it in the hovercard under the heading ‘Take a look inside’.

The rendering instructions for Word item hovercards is in the same location as Item_Word.js and its name is Item_Word_HoverPanel.js. I can edit this file with SharePoint Designer 2013, but in the grand tradition of SPD the way it’s done is a bit goofy. If you try to navigate to the folder that contains the templates through Master Pages in the Navigation pane it will say there are no files there, but you can get to them via All Files.

I am going to edit Item_Word_HoverPanel.js and add an inline style to change the color of the Take a look inside heading. Remember kids, inline styles are only good in simple demos! In real life use a style sheet!!!

If I refresh my search results and check the hovercard I can see it worked.

You can examine Item_Word_HoverPanel.js to get an idea of what is going on here, but there is a better way.

Design Manager: Edit Display Templates

Publishing sites provide an amazing new feature called Design Manager. Many people are writing about it so I will skip the high level discussion and get right to the point! But first, have some links:

http://blog.drisgill.com/2012/07/top-6-new-features-for-designers-in.html

http://bniaulin.wordpress.com/2012/07/18/sharepoint-2013-design-manager-convert-html-to-master-page

Publishing sites can generate the rendering JavaScript for you based on HTML templates. If you aren’t using publishing in your site you can still use as a publishing site as a development tool to cheat and create the JavaScript! The HTML templates are far easier to read and are an excellent place to start understanding what you need to do for your own custom rendering templates.

Open up a publishing site in SPD 2013 and use All Files to navigate to /_catalogs/masterpage/Display Templates/Search. You will see that the publishing site has many more files than the team site did and that each JavaScript file has an associated HTML file. To customize the hoverpanel I can simply edit the Item_Word_HoverPanel.html file and SharePoint will generate the correct JavaScript. This time I will make the heading purple.

Open the file and edit it. You will immediately see that the template is much easier to follow than the straight js version. Pay special attention to ctx object – it is the key to custom rendering. You can see that ctx gives access to the current item and that it provides methods for rendering via:

  • ctx.RenderHeader(ctx)
  • ctx.RenderBody(ctx)
  • ctx.RenderFooter(ctx)

I edit the file as follows:

And the result looks like this:

Conclusion – Letting SharePoint do Some of the Work

If I use the script debugger of my choice, in this case FireBug, I can see the resulting script.

Pretty cool eh!? I could then use this template in my Team site as desired.

This tutorial has barely scratched the surface of client rendering. As of this writing the SDK still isn’t out, but fortunately I had the unfortunate circumstance to reverse engineer much of the list rendering in 2010 so I will keep writing about it over the coming months until we get some good documentation. This stuff is important enough that I expect we’ll see some decent materials on the subject in the SDK.

–Doug

Author: Doug Ware