Introduction

In SharePoint 2010 we used XSLT to customize the look of lists and forms. Client Side Rendering (CSR) in SharePoint 2013 is the next step in easy customization and changing the look of SharePoint. CSR is based on JavaScript (and HTML), so its flexibility allows using it in sandbox solutions and SharePoint Online where there is no place to use code-behind.

Parts of SharePoint lists that can be customized this way are:

  • List view
  • Forms – Display, New, Edit Form
  • Fields

List view

The structure of a list view is as follows:

csr1

All those elements can be overwritten by a custom Rendering Template in Java Script. The elements in question are:

  • Header
  • Footer
  • View
  • Body
  • Group
  • Item
  • Fields

Two additional events are available

  • OnPreRender – data can be edited before they are displayed
  • OnPost Render – data are already rendered on site and are accessible by HTML DOM

View, Header, Body, and Footer can be called only once, while Group, Item, Field, as well as OnPreRender and OnPostRender events can be called multiple times.

Client Side Rendering API

To register a custom rendering template I will use SharePoint JavaScript method

SPClientTemplates.TemplateManager.RegisterTemplateOverrides(options)

It accepts a parameter of an object where I can define precisely which part of template I wish to override.

var overrideContext = {
  Templates: {
    View: /* function or string */,
    Body: /* function or string */,
    Header: /* function or string */,
    Footer: /* function or string */,
    Group: /* function or string */,
    Item: /* function or string */,
    Fields: {
      'Field Internal Name': {
          View: /* function or string */,
          EditForm: /* function or string */,
          DisplayForm: /* function or string */,
          NewForm: /* function or string */
      }
    }
  },
  OnPreRender: /* function or array of functions */,
  OnPostRender: /* function or array of functions */

Example of this function will be presented in the later part of this article.

Deploy the CSR template

First upload a JavaScript file with a rendering template to a document library where it would be accessible by web part. It is recommended to upload a script to Master Page Gallery library, as it is accessible in the whole Site Collection.

  1. Site Settings -> under Web Designer Galleries -> Master Pagescsr5
  2. Next select “JavaScript Display Template” in the Content Type drop-down and fill metadata.csr2
  3. Set JS Link in list webpart properties. You can use code-behind, set it declaratively in CAML in list or column schema, or manually edit JS Link Webpart Properties.You can set many JSLink scripts, dividing them using |.

Examples

List view without customization.

csr3

List view with custom template.

csr4

In the code below the effect is achieved by overwriting the View template

(function () {
    function renderViewBodyTemplate(ctx) {
        var listData = ctx.ListData;
        if (ctx.Templates.Body == '') {
            return RenderViewTemplate(ctx);
        }
        var customHtml = '
<div id="announcements">';
        for (var idx in listData.Row) {
            var listItem = listData.Row[idx];
            customHtml += '
<h1>' + listItem.Title + '</h1>
';
            customHtml += '
<div>' + listItem.Description1 + '</div>
';
        }
        customHtml += '</div>
';
        return customHtml;
    }

    SP.SOD.executeFunc("clienttemplates.js", "SPClientTemplates", function () {
        var overrideCtx = {};
        overrideCtx.Templates = {};
        overrideCtx.Templates.View = renderViewBodyTemplate;
        SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
    });
})();

In the code below the effect is achieved by overwriting “Header”, “Item”, and “Footer.

(function () {
    function renderItemTemplate(ctx) {
        var customHtml = '
<h1>' + ctx.CurrentItem.Title + '</h1>
';
        customHtml += '
<div>' + ctx.CurrentItem.Description1 + '</div>
';
        return customHtml;
    }

    SP.SOD.executeFunc("clienttemplates.js", "SPClientTemplates", function () {
        var overrideCtx = {};
        overrideCtx.Templates = {};
        overrideCtx.Templates.Header = '
<div id="announcements">';
        overrideCtx.Templates.Item = renderItemTemplate;
        overrideCtx.Templates.Footer = '</div>
';
        SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
    });
})();

If Minimal Download Strategy is enabled, the template should be registered by RegisterModuleInit function.

SP.SOD.executeFunc("clienttemplates.js", "SPClientTemplates", function() {
	function init() {
		SPClientTemplates.TemplateManager.RegisterTemplateOverrides({
			// overrides go here
		});
	}

	RegisterModuleInit(SPClientTemplates.Utility.ReplaceUrlTokens("~siteCollection/_catalogs/masterpage/yourtemplate.js"), init);
	init();
});

Summary

Pros:

  • Debugging is possible
  • Client-side rendering lessens server load
  • Many possibilities of customization

Cons:

  • The JSLink property is not supported on Survey or Events lists. A SharePoint calendar is an Events list.
  • Rendering performance depends on client’s computer and browser
  • Compability – different browsers can interpret code differently

 

 

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s