JSLink and SharePoint 2013 – How to Get Started

Introduction

JSLink is a new approach combining JavaScript, HTML and CSS elements to customize the look of a SharePoint list views, list forms, and can control the rendering of fields. JSLink was introduced with SharePoint 2013.

In this article we will learn how to customize the rendering of list view web parts with JSLink. This article will only scratch the surface of customization possibilities that JSLink offers.

The list view that we are going to customize is based on the ‘Tasks’ list template. We could have chosen a simple custom list to keep the overall technical implementation simple, however the visually appealing nature of a ‘% Complete’ bar in Tasks list is certainly worth the extra effort. Let’s see a Tasks list with CSR applied and then without.

Without CSR

With CSR

Steps

  1. Custom JavaScript (That will hold the CSR code)
  2. Upload the file to a SharePoint library
  3. Set JSLink property of list view web part

Custom Script with CSR Code

First, let’s try and understand the above code. In the first three lines, we create a JavaScript object that helps us customize how the field renders. As we are only interested in customizing a single field, the ‘%Complete’ fields property of the ‘Templates’ object, we reference only that field.

This fields property takes the following format: “FieldName” : {“Scope” : Override}

  • FieldName: Internal name of the filed
  • Scope: When to override it. Allowed values are “View”, “DisplayForm”, “EditForm”, and “NewForm”
  • Override: A text or HTML value. This can be a function that returns text or HTML

It’s the fourth line that registers the overriding context object (overrideCtx) with TemplateManager.

In this case I chose to use a function that returns HTML markup. The markup returned will replace the field value.

One thing to understand here is the function used for customization receives the overrideCtx object that is registered with TemplateManager. You can access quite a bit of information from this object. We are now done writing the custom JavaScript, and about 95% towards our goal. The remaining work involves uploading and referring through a web part property.

Uploading to Master Page Gallery

We can upload this file to any library, but it is recommended to do it through the Master Page Gallery and Display Templates folder. I have personally tested uploading it to the Style Library, which worked fine as well.

When you are uploading it to Master Page Gallery, choose the Content Type ‘Javascript Display Template’. Set the Target Control Type to ‘View’ in this case and Standalone option to ‘Overide’. The Target Scope is the relative URL of the site to which you want this CSR implementation to be applied.

Set the JSLink property for the Web Part

Set the JSLink web part property to the file location of the JavaScript file, in this case: ‘~sitecollection/_catalogs/masterpage/Display templates/TasksCSR.js’

A simple /_catalogs/****/TasksCSR.js link will not work. Either of the following SharePoint tokens should be used instead:

  • ~site
  • ~siteCollection
  • ~layouts
  • ~siteLayouts
  • ~siteCollectionLayouts

Once you have set the property you should then be able to see the result. We hope you found this tutorial useful, if you have any questions or comments please leave them below.


January 6, 2015
  • Super Dave

    I am using SharePoint Online for this tutorial. I have no subsites and will doing this tutorial from my Top Level site. What do I put for the “Target Scope” ??? Do I just put a “forward slash”