JSLink: Edit and New Form

This is my second post on JSLink and I will show how to customize "New" and "Edit" forms using JavaScript and JSLink. I will not spend time on setup and deployment, which I briefly touched on my last post here.

As a ShaePoint developer, most of us have worked on customizing New or Edit form using JavaScript which works but it's a workaround, not an elegant solution. But with JSLink, we don't have to add Content Editor web part to OOTB NewForm.aspx or EditForm.aspx, instead we just have edit the page and set JSLink property.

In this post I am using the same Tasks list as in previous post and will enhance the new and edit forms, by replacing "% Complete" input control with dropdown list with predefined values. Here is the final result:



To achieve this result, create JavaScript file and copy/paste following code snippets. See comments for explanation:

// JavaScript source code
(function () {
    var overrideCtx = {};
    overrideCtx.Templates = {};

    //override 'PercentComplete' field and provide custom rendering functions
    //for NewForm.aspx and EditForm.aspx pages.
    overrideCtx.Templates.Fields = {
        'PercentComplete': { 'NewForm': customField, 'EditForm': customField }
    }

    //register our override
    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

function customField(ctx) {
    //get form context for our field
    var formCtx = SPClientTemplates.Utility.GetFormContextForCurrentField(ctx);

    //local vars:
    var fldName = "cbo_" + formCtx.fieldName;    //used to set id of dropdown
    var fldValue = parseInt(formCtx.fieldValue); //get current value for edit form

    //register value callback. this function is called before submitting form
    //returned value will be saved in PercentComplete field. make sure the 
    //return type is compatible with field data type.
    formCtx.registerGetValueCallback(formCtx.fieldName, function () {
        var cbo = document.getElementById(fldName);
        return cbo.options[cbo.selectedIndex].value;
    });

    //return <select> html to replace input control
    var html = [];
    html.push("<select id='" + fldName + "'>");</select>
    html.push(getSelectItem(0, fldValue));
    html.push(getSelectItem(25, fldValue));
    html.push(getSelectItem(50, fldValue));
    html.push(getSelectItem(75, fldValue));
    html.push(getSelectItem(100, fldValue));
    
    return html.join('');
}

//build <option> tag 
function getSelectItem(value, selValue) {
    if (value === selValue) 
        return "<option selected='selected' value='" + value + "'>" + value + "'</option>";
    return "<option value='" + value + "'>" + value + "</option>";
}

Upload JS file to Master Page library and set metadata as below:

Content Type	JavaScript Display Template
Target Control Type	Form
Standalone	Override
Target Scope	Server relative URL of site
Target List Template Id	List template Id (optional)

At this point only task remaining is to edit "NewForm.aspx" / "EditForm.aspx" pages and set JSLink proerty of "ListFormWebPart". You can do this through UI (edit page), Feature receiver or PowerShell script.

Go back to Tasks list and add or edit item to see customization. In next post, will see how we can add custom field validation.

Hope this help.

-Javed

Working with JSLink

Recently I have been looking at CSR (client side rendering) feature which was introduced with SharePoint 2013. I did some display customizations with 2007 and 2010 version by modifying XSLT but when I try to replicate the same customizations with CSR feature, I immediately realized the power and usefulness of this new addition.

JSLink is the new property, available on many web parts, which allows you to override some parts or all of webpart UI on client side. SharePoint 2013 now uses JavaScript display templates to render contents on clients and falls back to XSLT, if for example: JavaScript is disabled on browser. This JavaScript framework provides many advantages compare to previous XSLT based rendering:

1. Not many developers are familiar with XSLT and it is difficult to develop XSLT and debug.
2. Most web developers are already familiar with JavaScript development.
3. CSR – JSLink are easy to deploy and rolling back customization are straight forward too.
4. With CSR – JSLink, the processing moves from server to client browser, thus freeing up server resources.

In this article, I will focus on overriding display of “% Complete” field of custom Tasks list. The goal is to display some kind of progress bar based on percent complete data. In order to implement this feature we have to follow below tasks:

1. Created JavaScript file with override code
2. Upload JavaScript file to SharePoint master page gallery using “JavaScript Display Template” content type
3. Set JSLink property of webpart.

Here are the details of each task and for this article I am using SharePoint UI to complete these task, but it can be deployed as WSP Solution.

Created JavaScript file with override code

Open notepad (or your favorite text editor) and copy/paste the following code:

(function () {
    //create override object
    var overrideCtx = {};
    overrideCtx.Templates = {};

    //we are interested in 'PercentComplete' field. 
    //Note: field name is Internal Field Name which may be 
    //different than display name
    //you can use SharePoint Manager 2013 to find internal field name
    overrideCtx.Templates.Fields = {
        'PercentComplete': { 'View': customField }
    }

    //these are optional, but in case of multiple webparts on 
    //page and these are not set will affect all list view.
    overrideCtx.BaseViewID = 1;
    overrideCtx.ListTemplateType = 100;

    //register the override
    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

//this function gets called for each row while rendering 'PercentComplete' field
function customField(ctx) {
    //check if 'PercentComplete' field is populated
    if (ctx.CurrentItem["PercentComplete"]) {
        //remove whitespace
        var completed = ctx.CurrentItem["PercentComplete"].replace(/\s+/g, '');
        //build and return the html to be rendered
        //NOTE: make sure you rename the red.png with your file on 15/images folder. 
        //Mine is 5x5 pixel with solid red
        var result = "<div style='background-image:url(/_layouts/15/images/red.png);width:" + completed + "'><b>" + completed + "</b></div>";
        return result;
    }
}

Upload JavaScript file to SharePoint master page gallery using “JavaScript Display Template” content type

• Navigate to Site Settings > Master pages and page layouts screen.
• From ribbon click “Upload Document” > Browse and select above JavaScript file > click OK
• On next screen; enter as follows:

Content Type	JavaScript Display Template
Target Control Type	Field
Standalone	Override
Target Scope	Server relative URL of site
Target List Template Id	List template Id (optional)

• Click “Save”

Set JSLink property of webpart

• Expand “Settings” menu and click on “Edit Page”
• Open webpart menu and click “Edit Web Part”
• Expand “Miscellaneous” tab and add JavaScript URL with site token eg: ~site/_catalogs/masterpage/CSRTasks.js
• Click “OK” to save.
• Save and close the edit page screen.

At this point you are ready for testing, hit F5 to refresh the list web part page and if all went fine the UI would look like this:



Next article will talk about overriding Edit and View forms.

Hope this helps.

-Javed