All you ever wanted to know about Client-Side Rendering in SharePoint 2013 – Part 1

Part 1 – Introduction to Client Side Rendering

Part 2 – Using TypeScript to build a client side rendered web control

Part 3 – Using KnockoutJS with Client Side Rendering and TypeScript to provide client side data binding.

Part 4 – Making use of the Design Manager to customize your web parts

There have been a few pretty major changes in SharePoint 2013. In my opinion one of the most significant, in terms of it’s impact for SharePoint application developers, is the prevalence of client side rendering. You’d be forgiven for looking at a SharePoint 2013 page and thinking “ok, so there’s a new master page and some metro-style CSS” but that really is the tip of the iceberg when it comes to UI changes in the new version. Client side rendering is everywhere. Unfortunately, although not unsurprisingly given the hype surround the app development model, there isn’t much technical content on client side rendering at the moment. In this post, I’m hoping to change that. At least a little bit!

So what’s client-side rendering?

SharePoint is designed to be configurable. We can change the data structure by adding custom content types and columns, we can change the business logic by adding event receivers and workflows and we can change the UI by adding and configuring web parts. But that’s not enough. To allow us to really customize the UI we need a templating mechanism. Web part configuration is great for changing how something works but can only go so far when it comes to changing what it looks like. In previous versions of SharePoint we used XSLT as a templating mechanism. Caught in the hubris of the day, we all worshipped at the XML alter and put our angle bracket skills to the test. And it worked! But there was a catch (possibly on one of those sharp edges) and the catch was performance. Since templates were rendered on the server it meant a performance hit for each web part on each page render. Maybe not a significant performance hit but when a lot of users start hitting those pages it makes a difference.

Enter client-side rendering (CSR). As the name suggests, CSR offloads the rendering responsibility to the client. Ta dah, instant performance boost! Thank you very much and good night.

That’s all very good but how does it work?

In short, it works using JavaScript – the future of rock and roll. Remember back in the day we had ASP classic? It was basically an HTML page with some instructions for adding content dynamically. The server picked up the page, dug up the appropriate data, and sent the generated content down the wire. Well CSR works in a similar way except the templates are processed on the client and the data to be added is either retrieved from a web service or passed to the client as an object. With CSR we have some server side code that builds a view model and then sends that view model down to the client to work it’s magic. In effect, we’re delegating UI work to the client and leaving the server to deal with data and business logic.

Why should I care?

Web parts can still work as they always have done. There’s nothing to stop us from building the UI programmatically on the server or using a visual web part and bringing in the UI from an ASCX file. So is it worth the effort to switch to CSR? I suppose the honest answer is: in some cases no. I’d argue that those cases are in the minority though and here’s why. Styling SharePoint was always a bit of a pain. It could be done but it wasn’t like downloading a WordPress theme – some time and money had to be spent. As a result, a lot of organizations didn’t bother. With 2013 it’s gotten way easier – still not ‘downloading a theme’ easy but pretty close. As a result, the turtleneck department in many organizations won’t tolerate ugly web parts corrupting the feng shui of their branded 2013 deployment. If all you you have in reserve is XSLT, you’re in for fun fun fun!

How can I use it?

So we can see why we really need to jump on the bandwagon here. Let’s look at how we get on board this thing.

CSR is built on top of a relatively simple script that can be found at {sharepoint root}/template/layouts/clientrenderer.js. I say “built on top of” because some of the cool stuff like the templating that’s used by the OOTB search web parts uses a pile of other scripts as well (but that’s a story for another day).

At the time of writing there is no documentation for clientrenderer on MSDN. Let’s start by remedying that.

The easiest way to explain what’s going on is via these two constructs:

(Of course JavaScript isn’t object oriented but I’ll use object oriented concepts such as classes and interfaces to illustrate what’s going on.)

Class:   SPClientRenderer


void Render (node, context)

The Render method is the main entry point for the client renderer. It accepts two parameters:

node – an HTML DOM object that will contain the rendered content.

context – an object that implements IViewModel view model that will be passed to the template to be rendered.

void RenderReplace (node, context)

Works in the same way as Render except node is replaced with the result of the rendering operation.

Interface: IViewModel

delegate ResolveTemplate(context, component, level)

This delegate is used to determine which template should be used for rendering content. It should return either a string, representing a static template or a delegate, representing a dynamic template.

delegate OnPreRender(context)

This delegate is called before the rendering process begins. It allows for further enrichment of the context object before processing begins.

delegate OnPostRender(context)

This delegate is called after the rendering process completes. Since template generated content has been added to the DOM at this point it’s possible for it to be acted upon by additional client scripts. (For example, initializing a JQuery plugin)

dictionary(string, delegate)  Templates

If no ResolveTemplate delegate is referenced by the context object the rendering template is determined by examining the Templates dictionary for a template with the key ‘View’. As with the ResolveTemplate delegate, the associated value can be a string in the case of a static template or a delegate in the case of a dynamic template.

The rendering process works as follows:

  1. Render method is called.
  2. A call back is made to the OnPreRender delegate defined on context (if one exists)
  3. The ResolveTemplate delegate defined on context is called (if one exists), returning a template delegate to be executed or a string to be returned.
  4. If ResolveTemplate is not defined an attempt to locate an appropriate template within the context objects Templates dictionary is made.
  5. If no template can be found an empty string is returned.
  6. If a template delegate has been found it is called passing the context object as it’s only parameter.
  7. The delegate will return a string which is returned as the result of the rendering operation.
  8. The Render method injects the generated HTML as a child of the node DOM object that was passed in.
  9. A call back is made to the OnPostRender delegate defined on context (if one exists)

(If RenderReplace was called, the generated HTML is added as a child of the node DOM object’s parent and then node is removed)


In this post I’ve covered the basics of Client-Side Rendering – what it is and why it’s worth knowing about. In the next post in this series I’ll look at how we can build on this knowledge to develop a client side rendered web control using TypeScript.

This entry was posted in HowTo, InDepth, JavaScript, SharePoint 2013 and tagged . Bookmark the permalink.
  • DannyE

    For use in 2010 and basic Field re-rendering one can also use the trick