An introduction to JSLink

You’ve probably heard about JsLink, but I guess you haven’t read any good documentation on it from Microsoft. The problem with JSLink is it’s not well documented. In this blogpost I’ll give you an introduction.


What is JsLink?

Basically JsLink is a JavaScript file which overrides the default view of you list. You can include the JavaScript file any way you want, but the standard way (and most aligned with SharePoint) is setting it under the Miscellaneous section of your list view web part. This makes sure that everything is loaded in the correct order.

JsLink-Miscellaneous

As you can see in the illustration above, I’ve used the token ~sitecollection before the site collection relative URL to my JavaScript file.

How to link up my JavaScript file?

You can’t enter the URL of your JavaScript any way you want. Microsoft are being quite strict on this. You need to start with either one of these tokens: ~site (for site relative) or ~sitecollection (site collection relative). This means you can’t link up a JavaScript file from another site collection (well, it is possible, but too advanced for this introduction).

How do I write my JsLink file?

There’s four main components in a JsLink file:

  • A function doing the override
  • A header function returning HTML
  • A footer function returning HTML
  • A item function returning HTML

A function doing the override

I normally use a self-executed function here, and I think that’s the way to go.

Here’s an example of an override of custom lists (which has the list template ID 100):

(function () {
 var overrideCtx = {};
 overrideCtx.Templates = {};
 overrideCtx.Templates.Header = CustomRenderer.HeaderHtml;
 overrideCtx.Templates.Item = CustomRenderer.ItemHtml;
 overrideCtx.Templates.Footer = CustomRenderer.FooterHtml;
 overrideCtx.BaseViewID = 1;
 overrideCtx.ListTemplateType = 100;
 
 SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

I start by creating a javascript object containing the object Templates and the properties BaseViewID and ListTemplateType.

In the object Templates you set the override functions for Header, Item and Footer. We’ll come back to this later in this post.

BaseViewID is not so important at this stage – we’ll come back to this property in later posts. ListTemplateType I’ve set to 100 which is a custom list.

Finally I give this object I’ve created as a parameter to the function SPClientTemplates.TemplateManager.RegisterTemplateOverrides. We’re done with the first part!

A header function returning HTML

This part is simple. This function should just return the HTML for your header. Normally you would return the start of a list:

return "<ul>";

or just the opening part of a div:

return "<div>";

A footer function returning HTML

Almost the same as the header functin. This function should just return the HTML for your footer. Normally you would return the end of a list:

return "</ul>";

or just the closing part of a div:

return "</div>";

A item function returning HTML

The item function gives you the ctx parameter which gives you everything you need for your view. In this example we’ll use the object CurrentItem under ctx.

CustomRenderer.ItemHtml = function(ctx) {
var title = ctx.CurrentItem.Title;
var modified = ctx.CurrentItem.Modified;
return "<li>" + title + " was modified " + modified + "</li>";
}

In the example above I’m retrieving the Title and Modified from the CurrentItem of the ctx which I get as a parameter to my function (These properties must be in the list view you’re overriding). Then I return a list item with these two properies combined. Remember to keep this function clean – don’t do too much! If your HTML becomes too complex you should look into a combination of CSOM/REST and Knockout/Angular. Concatenating HTML becomes VERY messy VERY fast.

Enjoy!

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