SharePoint / AngularJS App Seed Project

SharePoint list conditional formatting with JSLink

by Martin Laukkanen | Dec 9, 2013 | Development, How to, SharePoint 2013

This is one of the new features of SharePoint 2013 that I have been looking forward to trying out since I first read about it; as someone who has often uses JavaScript to enhance the usability of Project Server JSLink is a perfect feature to make these customisation’s simply and in a supportable way.

JSLink in Action

Check out my Exposure column on an otherwise default Project Site risk list! :)

JSLink enables the client-side rendering to be customised with just about any JavaScript or html changes that you think of, and better yet not only does it apply to views, but also New and Edit forms. For me that means I will probably never suggest InfoPath forms to a customer again!

Example Updating the Project Site Template

The screenshot above shows a simple example of a JSLink script configured on the project site out-of-the-box Risks list, to demonstrate how to do that quickly and easily against an existing list (or your Project Workspace Site template), first you need a bit of JavaScript:

JSLink script riskColor.js

Type.registerNamespace('CustomFormat');

CustomFormat.riskColor = function () {

    var riskFieldsContext = {};
    riskFieldsContext.Templates = {};
    riskFieldsContext.Templates.Fields = {
        "Exposure": { "View": CustomFormat.exposureColourTemplate }		
    };

	SPClientTemplates.TemplateManager.RegisterTemplateOverrides(riskFieldsContext);
}

// This function provides the rendering logic for list view
CustomFormat.exposureColourTemplate = function(ctx) {

	var fieldValue = ctx.CurrentItem[ctx.CurrentFieldSchema.Name];

	if (parseFloat(fieldValue) > 7) {
		return "<span style='background-color : red'>&nbsp;&nbsp;&nbsp;&nbsp;</span> High (" + fieldValue + ")";
	}
	else if (parseFloat(fieldValue) > 4) {
		return "<span style='background-color : gold'>&nbsp;&nbsp;&nbsp;&nbsp;</span> Medium (" + fieldValue + ")";
	}
	else {
		return "<span style='background-color : green'>&nbsp;&nbsp;&nbsp;&nbsp;</span> Low (" + fieldValue + ")";
	}
}

//CSR-override for MDS disabled site 
CustomFormat.riskColor();

if (typeof _spPageContextInfo != "undefined" && _spPageContextInfo != null) {    		
	// CSR-override for MDS enabled site
	RegisterModuleInit(_spPageContextInfo.siteServerRelativeUrl + "/SiteCollectionDocuments/riskColor.js", CustomFormat.riskColor); 
}

In summary what is happening is the following:

On line 8 inside the CustomFormat.riskColor() function I define the field names which we want to customise and specify the formatting callback function for the type of customisation, in this case we are customising the “View” but we could use “DisplayForm”, “NewForm” or “EditForm” here also.

Two things to note here, firstly make sure you use the Internal Name of your field, so for instance if you created a custom column called “Risk Rating” then that would be “Risk_x0020_Rating”, secondly you can specify as many fields / columns by name here as you want each with a separate formatting function.

For more details on JSLink and all the other options available I’d recommend the following reading:

• JSLink and Display Templates Part 1 – Overview, URL Tokens and Applying JSLink to objects (Make sure to check out all parts of this great series)

Next from line 19 to 26 in the CustomFormat.exposureColorTemplate() function I simply return our modified HTML based on the value of the field in question, in this example I’m comparing the number against three arbitrary values for High, Medium and Low, then returning a html string including a colour and some text to emphasize the value.

Finally and thanks to Wictor Wilen for his article on fixing the issues caused by MDS (SharePoint’s Minimal Download Strategy feature) I’m registering and then executing the script properly when called.

Registering the JSLink Script

Now that we have our script, we just need to register it in our site template, so to do so first save your script somewhere central in your site collection, I personally like Site Collection Documents under PWA, but wherever it is make sure everyone has access.

Secondly open your Risks list view and Edit Page from the SharePoint menu. With the page in Edit mode click the dropdown arrow for the Risks list web part and select Edit Web Part:

Now in the Web Part Properties expand Miscellaneous and locate the JS Link field:

The full path I’m using is:

~sitecollection/SiteCollectionDocuments/riskColor.js

This path also is referenced at the bottom of the script as _spPageContextInfo.siteServerRelativeUrl + “/SiteCollectionDocuments/riskColor.js” so make sure to set both correctly.

NOTE: I’ve found this step is critical, the “~sitecollection” token is REQUIRED in the web part misc properties! At least in my case I was able to consistently cause IE to throw script errors if I tried to use a relative path like /PWA/SiteCollectionDocuments/riskColor.js! It did work in Chrome so maybe it is something in IE? Either way you can replace that with ~site ,or ~layouts as required.

Finally save your webpart configuration and it should immediately work.

Final Words

A few things; firstly double check the URL using in the Web Part properties and make certain to specify the path correctly in both the script and the web part properties. If you noticed the views fail (I did many times) then double check the note above about the ~sitecollection token.

Secondly because we are using the out-of-the-box Risks list we must add this JS Link script reference to every view and web part display of our Risks list.

Thirdly clear your browser cache! This one had me stumped as it seemed like none of my changes were working when in fact the script changes were not being refreshed, I found disabling the cache (easy in F12 mode in Chrome) made testing this super easy.

Finally for a bunch of cool examples of JSLink in action don’t forget to have a look at:

http://code.msdn.microsoft.com/office/Client-side-rendering-JS-2ed3538a

I hope you find this useful.