Display Templates for Site Columns – Harvey Balls

So one of the little things with XSL that has bugged me is that it seems harder to change just one column than it should be – and of course, you have to apply the XSL every time you want a view to be changed. I have recently managed to spend a bit of time taking a look at 2013 Display Templates and I was very excited to find that this resolves both of these issues by allowing a Display Template to be attached to a Site Column.

This means that every time that Site Column is added to a list, your custom Display Template will be applied to it – very nice.

But the goodness does not stop there. Within the Display Template you can also change how the column appears depending on what you are doing with it – so in create or edit mode it can look completely different to view or display mode. This opens up a whole range of exciting possibilities.

Sitting at Auckland airport after the New Zealand SharePoint Conference last month I had the pleasure to sit and discuss this with Marc Anderson who wondered if it was possible to show Harvey Balls in this way. Well that seemed like an opportunity too good to miss so here we go.

Site Column
Firstly we need to create our Site Column. I am going to assume you know how to create a site column but the properties we need are below:
Column Name: HarveyBalls
Type: Choice
Choices: 0, 1, 2, 3, 4
Display Using: Radio Buttons

Good start. What I usually do is then edit the Site Column and change the Name to a more friendly display name – in this case: Harvey Balls.

So, our column at this point is ready to be added to any list or library but will simply display as a radio button offering the choices from 0-4.

Display Template
Again, there are some great blogs and articles out there on the basics of creating Display Templates so I am not going to go into too much background.

My first attempt used Unicode characters which was nice and simple but did not look great. A CSS version of Harvey Balls added a tiny bit more complexity to the script but looked much better.

My Display Template can be found on GitHub and that is definitely the best way to grab a copy for your own use. I will also not try quoting the full script here as it never seems to play nicely!

First we define our namespace and a function to display our field. Within this function we have an array with 5 options to match our choices (0-4) which are actually the CSS classes we want.

var balls = ["harvey", "upper-right", "harvey half-right", "three-quarters", "harvey black"];

We then get the current selected value of our field which will be 0-4 and just to be safe set it to 0 if it is empty:

var ball = ctx.CurrentItem[ctx.CurrentFieldSchema.Name];
if (ball == "") {
	ball = 0;

A string is then constructed containing a DIV with the class set to the value from our array which matches the choice value:

var ret = "";
switch (ball) {
	case "1":
		ret = "<div class='harvey'><div class='" + balls[ball] + "'><i></i></div></div>";
	case "3":
		ret = "<div class='harvey black'><div class='" + balls[ball] + "'><i></i></div></div>";
		ret = "<div class='" + balls[ball] + "'><i></i></div>";

Our string is then returned and this HTML is what is put on the page to represent our Site Column.

I chose to make the Display Template completely standalone so the next section in the script adds the required CSS to the page to present our Harvey Balls. This could also just be added to a standard CSS file.

Finally, we define template object and register it with SharePoint:

var fieldCtx = {};
fieldCtx.Templates = {};
fieldCtx.Templates.Fields = {
	"HarveyBalls": {
		"View": paylord.harveyBalls.viewFieldTemplate,
		"DisplayForm": paylord.harveyBalls.viewFieldTemplate

Note that in this case we are only changing the way the field looks in view and display modes.

These scripts can be saved anywhere but I usually add them to a custom folder in my Style Library.

Now, unfortunately Microsoft seem to have forgotten to add the JSLink property to the UI of Site Columns so the simplest way to link our script to our Site Column is a few lines of PowerShell:

$web = Get-SPWeb "http://sitename"
$field = $web.Fields["Harvey Balls"]
$field.JSLink = "~sitecollection/Style Library/custom/HarveyBalls.js"

I have simplified the PowerShell here but the GitHub version linked above will prompt for the values it needs. Main thing to note here is the “~sitecollection” element as part of the path – make sure you include this or one of the other alternatives depending upon where you have saved the file. Relative paths and even full paths do not seem to work well.

That is it! You can now add your Site Column as usual to any list or library, be able to choose 0-4 from the radio button and this will then be displayed as the related Harvey Balls icon when in view or display mode.

Harvey Balls

I will definitely being doing some more of these so watch this space!

This entry was posted in SharePoint and tagged , , , , . Bookmark the permalink.

2 Responses to Display Templates for Site Columns – Harvey Balls

  1. Pingback: Harvey Balls Redux – Display Templates for Site Columns by Dave Paylor | Marc D Anderson's Blog

  2. Pingback: Display Templates – Colour Picker | Paylord

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 )

Google+ photo

You are commenting using your Google+ 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 )

Connecting to %s