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.
Step 1: Setting it up
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.
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.
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