JSLink and Display Templates Part 1 – Overview, URL Tokens and Applying JSLink to objects

This is the first in a 4 part series about JSLink where I intend to go through all the ins and outs of using Display Templates to customise list rendering.

This first section really covers off the basics. It doesn’t contain any real sample code about the Display Templates (that is in Parts 2, 3 and 4) but does explain what JSLink is and how you can apply it to different objects.

What is “JSLink” exactly?
I think there has been a fair amount of confusion over what the terminology “JSLink” actually means. I’ve commonly seen it referred to as the technology which allows you to customising field and list rendering but that is really the Display Template functionality.

In a nut-shell JSLink simply means “link to my JavaScript file”

This is basically a URL to a JavaScript file. It doesn’t really matter where this file is (it could just as easily be in a document library or the Layouts folder). There are a vast number of objects you can attach JSLink references to but the ones we are really interested are:

  • Site Columns
  • Content Types
  • List Views
  • List Forms (e.g. New / Edit / Display forms)
  • List View Web Parts
  • List Form Web Parts

This gives us the full battery of places that we need in order to get our JavaScript in the right place at the right time, some of which are clearly desirable for different reasons.

JSLink URLs and Tokens
When you are constructing your JSLink URL there are a number of tokens you can take advantage of:

  • ~site – reference to the current SharePoint site (or “Web”)
  • ~sitecollection – reference to the current SharePoint site collection (or “Site”)
  • ~layouts – version specific reference to the web application Layouts folder (so it will automatically swap out /_layouts/14 or /_layouts/15 for you)
  • ~sitecollectionlayouts – reference to the layouts folder in the current site collection (e.g. /sites/team/_layouts/15)
  • ~sitelayouts – reference to the layouts folder in the current site (e.g. /sites/teams/subsite/_layouts/15)

This allows you to easily make sure that your JSLink files are targeted correctly (whether you are provisioning them to a specific library, or want to make sure your _layouts URL is constructed appropriately).

You can also apply more than one JSLink reference at a time by separating each reference with the pipe | symbol. So if you wanted to include two custom JSLink files on a field you might use the following attribute:

JSLink=~sitecollectionlayouts/MJH/JSLink1.js|~sitecollectionlayouts/MJH/JSLink2.js

Applying your JSLink References
You have a whole range of different options for applying your JSLink to the different objects, and this will largely depend on where you want your customisations to be applied.

If you are creating a new custom field type then you would implement it at the Site Column level. If you want to do something specific such as cascading drop-downs then you might want to do that at the Content Type or List (form) level.

If you are doing a one-off demo in an environment where you don’t have a high level of permissions then you can apply the JSLink references to the List View or Form Web Parts (although appreciate that this obviously doesn’t scale particularly well as you would have to manually apply it to each web part).

You can apply them using XML as part of your Site Column, Content Type or List View definitions. Each of these contains a JSLink attribute which you can use to populate a URL

JSLink=~sitecollectionlayouts/MJH/JSLink1.js

You can also apply them to the above, as well as list forms using Server Side Code (I’m not sure if there is a client side object model equivalent).

SPList list = web.Lists.TryGetList(“My List”);
if (list != null)
{  SPForm editForm = list.Forms[PAGETYPE.PAGE_EDITFORM];
  editForm.JSLink = “~sitecollectionlayouts/MJH/JSLink1.js”;
}

You can even do this in PowerShell if you are properly hardcore 🙂

$web = Get-SPWeb https://teamsite.mjh
$field = $web.Fields[“MJHSampleField”]
$field.JSLink = “~layouts/MJH/JSLink1.js”
$field.Update($true)

And finally you can set this in the List View Web Part or List Form Web Part using the web part properties:

Add your JSLink reference to Web Part properties

There is also a final option where it seems you can create re-usable templates by uploading your templates into the Master Page Gallery so they appear as new “View Types” when users are creating new Views for their lists, but more about that in Part 5!

So that covers all of the basics about what JSLink actually is, how the URLs are constructed and how you can apply them. In the next few parts we will be looking at the sample code and walking through some real-world examples of how you can use JSLink along with Display Templates to implement custom field and view rendering.

Next: Part 2 – Changing how individual fields display

  • Johnny5a

    looks like the image link above works in IE but not FF. Turns out IE is more forgiving with forward slashes in the URL.

  • Martin Hatch

    Ok, amazed and embarrassed it took this long to fix that. Thanks!

  • Isaac Sogunro

    What is the difference between CSR and JSLink? I thought they were the same for a while until I came across your definition. “In a nut-shell JSLink simply means link to my JavaScript file”

    • Verth

      Its the same thing, just different terminology

    • Martin Hatch

      They are actually two very different things, although they tend to get used interchangeably (even by the SharePoint team themselves, I’ve seen CSR described as “JSLink” by Microsoft at the recent SharePoint Framework announcements)
      Essentially:
      JSLink – Is the mechanism through which your JavaScript files can be associated with an entity (such as a Content Type, List or Field). This can be ANY JavaScript file, and they can do anything you wish
      Client Side Rendering (CSR) – Is the framework through which you can override the rendering of SharePoint fields in both forms and views, as well as their validation and processing logic.
      You can use CSR without using JSLink (you can just drop in your JavaScript using a Script Editor Webpart, either through a link to a JavaScript file, or inline in Script tags).
      Equally, you can use JSLink without using CSR (for example to add custom Analytics or Logging when people are, for example, responding to Surveys)