Customising the NewForm with JSLink

In my last blog post about Client Side Rendering, Introduction to Client Side Rendering in SharePoint 2013, I covered what it is and how to create a simple ‘Percent Complete’ bar for each task by overriding the ‘View’ Form. This time, I’m going to override the New Form to create a task progress slider.

At the time of writing this, there’s very little information around on customising fields in the New forms. In the process of writing this, I found this blog post very useful. http://www.lestersconyers.com/custom-field-rendering-with-jslink/. It covers everything needed to override not only the New Form, but the Edit and Display forms as well. A lot of the code here comes from this blog, so I really recommend giving it a read. You may also find this MSDN article useful. http://msdn.microsoft.com/en-gb/library/jj163799.aspx. Its very code heavy, with very little explanation, however also covers creating custom templates for list forms.

Overview

This example is building on the example I built for my last blog. This means that the basis is still the same. You can grab a copy of the previous JS file here. I am using a single JavaScript file, which is dynamically loading in jQuery, and jQuery UI from the Google CDN to take care of all of the sliding. I’m using a standard Tasks list for this demo, however the principles are the same for any type of list.

Steps

Step 1: Setting it up

The first thing that has to be done to get the Slider to render on the New Form is to add the JSLink. Create a new JavaScript file in a library which is accessible to all users. I called mine ‘rb.rendering.js’. Leave the JS file empty for now, as I’ll cover the code further into the blog. Next, navigate to your list, and in the ribbon select ‘Form Web Parts > Default New Form’. This opens the New Form in edit mode.

Now, edit the web part, and expand “Miscellaneous”.

Under JS Link, add the link to the JS file which you just created. This must use the ‘~site’ or ‘~sitecollection’ token to work successfully, otherwise the JS file may not get rendered onto the page. This is the only setting which needs to be changed.

If you just want to use the example slider shown above, you can stop here, and upload my JavaScript file. If however, you want to see how the JS is built, read on.

Step 2: Writing the JavaScript

The JavaScript for this is relatively straight forward. I’ve added in a new function which takes care of building the HTML, and some jQuery which creates the slider. This is then referenced by the overrideCtx which was built up in my last blog.

The self-executing function at the top now looks like this:

This is building up the overrideCtx object just as before. The Fields object is pointing to the PercentComplete field. If you’re using a different column, you’ll need to update this to point to your columns internal name. Now this is where the only change is in this function: I’ve added the “NewForm : newPercentComplete” line. This instructs SharePoint to execute the “newPercentComplete” function on the New Form.

The newPercentComplete function does 3 things. Firstly, it sets up a way of telling SharePoint what the value of the column is. When the user clicks “Save”, this function is responsible for telling SharePoint that the task is, for example, 23% complete. In the example below, you can see it’s getting the “rb-value” element, and returning the value. This item is the input box which will be built in a couple of lines time.

The next thing it does, is set up some validation. This handles any validation events that may occur, such as a required field being left blank, or in the case of the task list, a number less than 0, or greater than 100 being entered. The first section is creating a validator object. Lines 35 – 37 then check to see if the field is required, and if so, adds a validator to the object. Lines 38 – 40 then register the validator, which ensures that it is called at the right time.

Lines 41-43 handles any error messages that occur. Rb-slider is the name of a div which is set up in the next few lines. Without these lines, no error message would be displayed, but the save button would not work if there were validation errors.

Lastly, it builds some HTML to display the custom rendering. This HTML can be anything you want, and is returned as a string. For this case, it’s returning a simple div, and an input box, with a little bit of inline CSS. Doing this properly, this CSS should be broken out into a CSS file to make it more reusable and manageable. This HTML is very simple, as most of the magic happens later on, when jQuery UI transforms this into a useful sliding element.

At this point, all of the SharePoint specific JavaScript is complete. This means its fully functioning and you could just stop there. For my example though, I want to add the slider. For this, I need jQuery UI.

Using jQuery in the New Form JavaScript

So that this example only requires adding 1 JavaScript file, I’m dynamically loading in jQuery from within this file. If you’d like to use a customisation like this throughout your site, it would be a good idea to implement jQuery in your master page, rather than referencing it multiple times in different locations. I’m using the loadScript function with callback from this blog, to ensure jQuery has loaded before it’s used:

http://www.jquery4u.com/javascript/dynamically-load-jquery-library-javascript/

I’ve also created another function “loadCss”, which does the same thing for loading the jQuery CSS. Without this, the jQuery UI Slider wouldn’t show up properly:

Now these functions have been set up, it’s time to call them. The next few lines load the CSS, jQuery and jQuery UI files, and when that’s complete, calls the “createSlider” function.

The createSlider function comes straight from the example over at the jQuery UI site. The only changes I’ve made are to the IDs of the elements.

Stepping through the code, the first line creates a self-executing function within jQuery. Then it runs the “slider” function on the element with the ID “rb-slider” (created earlier). The next few lines set up the properties, ensuring the user can’t drag below 0 or above 100, and the starting number is 0. Next it attaches an event to the “slide” event, which updates the element with the id “rb-value”, which is the input box. Lastly, it sets the value of the input, to ensure that it has a value on page load.

Trying it out

The last thing to do, is save the file and try it out. Go ahead and try adding a new item to the list. You should be seeing something like this:

As always, you can download the completed file here