SharePoint 2013 - Client Side Rendering

1. Client side rendering 代码结构为：

(function () {
    // Create object that have the context information about the field that we want to change it's output render 
    var linkFilenameFiledContext = {};
    linkFilenameFiledContext.Templates = {};
    linkFilenameFiledContext.Templates.Fields = {
        // Apply the new rendering for LinkFilename field on list view
        "LinkFilename": { "View": linkFilenameFiledTemplate }
    };
    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(linkFilenameFiledContext);
})();

2. Client Side Rendering 可以用来注册一个对象，这个对象用于去进行模板覆盖，对象包含以下几种属性：

View
Header
Body
Footer
Group
Item
Fields
OnPreRender
OnPostRende

3. Fields属性的格式为：overrideCtx.Templates.Fields = {FieldName : {Scope : Override}}, 使用ctx.CurrentFieldSchema.Name 来获取field的内部名称，例如：var priorityValue = ctx.CurrentItem[ctx.CurrentFieldSchema.Name]

FieldName - This is the internal name of the field you want to override.
Scope – This defines when to override the field. The choices are “View”,”DisplayForm”,”EditForm”, and “NewForm”.
Override – The actual override. This can be a HTML string with JavaScript embedded, or a function to be executed. In the former, it should be in the format: “<p> <#= ctx.CurrentItem.PercentComplete #></p>”, where “<p>” is just some HTML, and everything enclosed in “<#= #>” is JavaScript to be executed.

4. 使用clientform.js, clientpeoplepicker.js, 和autofill.js文件来生成client people picker：

页面代码：

<SharePoint:ScriptLink name="clientforms.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="clientpeoplepicker.js" runat="server" LoadAfterUI="true" Localizable="false" />
    <SharePoint:ScriptLink name="autofill.js" runat="server" LoadAfterUI="true" Localizable="false" />
<div id="peoplePickerDiv"></div>

JS代码：

function initializePeoplePicker(peoplePickerElementId) {

    // Create a schema to store picker properties, and set the properties.
    var schema = {};
    schema['PrincipalAccountType'] = 'User,DL,SecGroup,SPGroup';
    schema['SearchPrincipalSource'] = 15;
    schema['ResolvePrincipalSource'] = 15;
    schema['AllowMultipleValues'] = true;
    schema['MaximumEntitySuggestions'] = 50;
    schema['Width'] = '280px';

    // Render and initialize the picker. 
    // Pass the ID of the DOM element that contains the picker, an array of initial
    // PickerEntity objects to set the picker value, and a schema that defines
    // picker properties.
    this.SPClientPeoplePicker_InitStandaloneControlWrapper(peoplePickerElementId, null, schema);

5. 修改View或者Field的显示方式时，需要使用clienttemplate.js文件，参考示例；

具体操作为：先创建一个对象来存储要更改对象的上下文信息，然后使用SPClientTemplates.TemplateManager.RegisterTemplateOverrides（）来注册这个对象进行覆盖；

修改View显示方式的JS代码：

(function () {

    // Initialize the variable that store the objects.
    var overrideCtx = {};
    overrideCtx.Templates = {};


    // Assign functions or plain html strings to the templateset objects:
    // header, footer and item.
    overrideCtx.Templates.Header = "<B><#=ctx.ListTitle#></B>" +
        "<hr><ul id='unorderedlist'>";

    // This template is assigned to the CustomItem function.
    overrideCtx.Templates.Item = customItem;
    overrideCtx.Templates.Footer = "</ul>";

    // Set the template to the:
    //  Custom list definition ID
    //  Base view ID
    overrideCtx.BaseViewID = 2;
    overrideCtx.ListTemplateType = 10057;

    // Assign a function to handle the
    // PreRender and PostRender events
    overrideCtx.OnPreRender = preRenderHandler;
    overrideCtx.OnPostRender = postRenderHandler;

    // Register the template overrides.
    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrideCtx);
})();

// This function builds the output for the item template,
// it uses the context object to access announcement data.
function customItem(ctx) {

    // Build a listitem entry for every announcement in the list.
    var ret = "<li>" + ctx.CurrentItem.Title + "</li>";
    return ret;
}

// The preRenderHandler handles the 
// OnPreRender event
function preRenderHandler(ctx) {

    // Override the default title with user input
    ctx.ListTitle = prompt("Type a title", ctx.ListTitle);
}

// The postRenderHandler handles the 
// OnPostRender event
function postRenderHandler(ctx) {

    // You can manipulate the DOM
    // in the postRender event
    var ulObj;
    var i, j;

    ulObj = document.getElementById("unorderedlist");
    
    // Reverse order the list
    for (i = 1; i < ulObj.children.length; i++) {
        var x = ulObj.children[i];
        for (j = 1; j < ulObj.children.length; j++) {
            var y = ulObj.children[j];
            if(x.innerText<y.innerText){                  
                ulObj.insertBefore(y, x);
            }
        }
    }
}

 修改Field显示方式的JS代码（可以为Field提供View, DisplayForm, EditForm, NewForm的显示模板）：

// List View – Priority Color Sample
// Muawiyah Shannak , @MuShannak

(function () {

    // Create object that have the context information about the field that we want to change it's output render 
    var priorityFiledContext = {};
    priorityFiledContext.Templates = {};
    priorityFiledContext.Templates.Fields = {
        // Apply the new rendering for Priority field on List View
        "Priority": { "View": priorityFiledTemplate }
    };

    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(priorityFiledContext);

})();

// This function provides the rendering logic for list view
function priorityFiledTemplate(ctx) {

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

    // Return html element with appropriate color based on priority value
    switch (priority) {
        case "(1) High":
            return "<span style='color :#f00'>" + priority + "</span>";
            break;
        case "(2) Normal":
            return "<span style='color :#ff6a00'>" + priority + "</span>";
            break;
        case "(3) Low":
            return "<span style='color :#cab023'>" + priority + "</span>";
    }
}

为Field提交时注册事件的JS代码：

(function () {

    // Create object that have the context information about the field that we want to change it's output render 
    var ageFiledContext = {};
    ageFiledContext.Templates = {};
    ageFiledContext.Templates.Fields = {
        // Apply the new rendering for Age field on New and Edit forms
        "Age": {
            "NewForm": ageFiledTemplate,
            "EditForm": ageFiledTemplate
        }
    };

    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(ageFiledContext);

})();


// This function provides the rendering logic
function ageFiledTemplate(ctx) {

    var formCtx = SPClientTemplates.Utility.GetFormContextForCurrentField(ctx);

    // Register a callback just before submit.
    formCtx.registerGetValueCallback(formCtx.fieldName, function () {
        return document.getElementById('inpAge').value;
    });

    // Render Html5 input (number)
    return "<input type='number' id='inpAge' min='0' max='110' value='" + formCtx.fieldValue + "'/>";
}

 

6. 在除浏览器地址栏之外的其它地方，尽量不要使用%20替代空格，否则，在非IE浏览器（例如Chrome）中不能够识别，比如：

此处如果使用%20，则在Chrome中不能工作; 

 

而且不能使用绝对路径或者相对路径，要使用token符号来替代web路径，详情参考此页面；

JSLink URLs and Tokens
When you are constructing your JSLink URL there are a number of tokens you can take advantage of:

~site – reference to the current SharePoint site (or “Web”)
~sitecollection – reference to the current SharePoint site collection (or “Site”)
~layouts – version specific reference to the web application Layouts folder (so it will automatically swap out /_layouts/14 or /_layouts/15 for you)
~sitecollectionlayouts – reference to the layouts folder in the current site collection (e.g. /sites/team/_layouts/15)
~sitelayouts – reference to the layouts folder in the current site (e.g. /sites/teams/subsite/_layouts/15)

 

 7. 为Field添加验证时需要用到 SPClientForms.ClientValidation 对象

　　 var validators = new SPClientForms.ClientValidation.ValidatorSet();
    validators.RegisterValidator(new emailValidator());

    // Validation failure handler.
    formCtx.registerValidationErrorCallback(formCtx.fieldName, emailOnError);

    formCtx.registerClientValidator(formCtx.fieldName, validators);


// Custom validation object to validate email format
emailValidator = function () {
    emailValidator.prototype.Validate = function (value) {
        var isError = false;
        var errorMessage = "";

        //Email format Regex expression
        var emailRejex = /\S+@\S+\.\S+/;
        
        if (!emailRejex.test(value) && value.trim()) {
            isError = true;
            errorMessage = "Invalid email address";
        }

        //Send error message to error callback function (emailOnError)
        return new SPClientForms.ClientValidation.ValidationResult(isError, errorMessage);
    };
};

// Add error message to spnError element under the input field element
function emailOnError(error) {
    document.getElementById("spnError").innerHTML = "<span role='alert'>" + error.errorMessage + "</span>";
}

8. 设置Field为只读时，可以使用SharePoint已有的javascript方法：

// List add and edit – ReadOnly SP Controls Sample

(function () {

    // Create object that have the context information about the field that we want to change it's output render 
    var readonlyFiledContext = {};
    readonlyFiledContext.Templates = {};
    readonlyFiledContext.Templates.Fields = {
        // Apply the new rendering for Age field on Edit forms
        "Title": {
            "EditForm": readonlyFieldTemplate
        }
    };

    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(readonlyFiledContext);

})();

// This function provides the rendering logic
function readonlyFieldTemplate(ctx) {

    //Reuse ready sharepoint javascript libraries
    switch (ctx.CurrentFieldSchema.FieldType) {
        case "Text":
        case "Number":
        case "Integer":
        case "Currency":
        case "Choice":
        case "Computed":
            return SPField_FormDisplay_Default(ctx);

        case "MultiChoice":
            prepareMultiChoiceFieldValue(ctx);
            return SPField_FormDisplay_Default(ctx);

        case "Boolean":
            return SPField_FormDisplay_DefaultNoEncode(ctx);

        case "Note":
            prepareNoteFieldValue(ctx);
            return SPFieldNote_Display(ctx);

        case "File":
            return SPFieldFile_Display(ctx);

        case "Lookup":
        case "LookupMulti":
                return SPFieldLookup_Display(ctx);           

        case "URL":
            return RenderFieldValueDefault(ctx);

        case "User":
            prepareUserFieldValue(ctx);
            return SPFieldUser_Display(ctx);

        case "UserMulti":
            prepareUserFieldValue(ctx);
            return SPFieldUserMulti_Display(ctx);

        case "DateTime":
            return SPFieldDateTime_Display(ctx);

        case "Attachments":
            return SPFieldAttachments_Default(ctx);

        case "TaxonomyFieldType":
            //Re-use ready sharepoint inside sp.ui.taxonomy.js javascript libraries
            return SP.UI.Taxonomy.TaxonomyFieldTemplate.renderDisplayControl(ctx);
    }
}

//User control need specific formatted value to render content correctly
function prepareUserFieldValue(ctx) {
    var item = ctx['CurrentItem'];
    var userField = item[ctx.CurrentFieldSchema.Name];
    var fieldValue = "";

    for (var i = 0; i < userField.length; i++) {
        fieldValue += userField[i].EntityData.SPUserID + SPClientTemplates.Utility.UserLookupDelimitString + userField[i].DisplayText;

        if ((i + 1) != userField.length) {
            fieldValue += SPClientTemplates.Utility.UserLookupDelimitString
        }
    }

    ctx["CurrentFieldValue"] = fieldValue;
}

//Choice control need specific formatted value to render content correctly
function prepareMultiChoiceFieldValue(ctx) {

    if (ctx["CurrentFieldValue"]) {
        var fieldValue = ctx["CurrentFieldValue"];

        var find = ';#';
        var regExpObj = new RegExp(find, 'g');

        fieldValue = fieldValue.replace(regExpObj, '; ');
        fieldValue = fieldValue.replace(/^; /g, '');
        fieldValue = fieldValue.replace(/; $/g, '');

        ctx["CurrentFieldValue"] = fieldValue;
    }
}

//Note control need specific formatted value to render content correctly
function prepareNoteFieldValue(ctx) {

    if (ctx["CurrentFieldValue"]) {
        var fieldValue = ctx["CurrentFieldValue"];
        fieldValue = "<div>" + fieldValue.replace(/\n/g, '<br />'); + "</div>";

        ctx["CurrentFieldValue"] = fieldValue;
    }
}

 8. 隐藏Field时，可以在OnPostRender事件中使用jQuery方法：

(function () {

    // jQuery library is required in this sample
    // Fallback to loading jQuery from a CDN path if the local is unavailable
    (window.jQuery || document.write('<script src="//ajax.aspnetcdn.com/ajax/jquery/jquery-1.10.0.min.js"><\/script>'));

    // Create object that have the context information about the field that we want to change it's output render 
    var hiddenFiledContext = {};
    hiddenFiledContext.Templates = {}; 
    hiddenFiledContext.Templates.OnPostRender = hiddenFiledOnPreRender;
    hiddenFiledContext.Templates.Fields = {
        // Apply the new rendering for Age field on New and Edit forms
        "Predecessors": {
            "NewForm": hiddenFiledTemplate,
            "EditForm": hiddenFiledTemplate
        }
    };

    SPClientTemplates.TemplateManager.RegisterTemplateOverrides(hiddenFiledContext);

})();


// This function provides the rendering logic
function hiddenFiledTemplate() {
    return "<span class='csrHiddenField'></span>";
}

// This function provides the rendering logic
function hiddenFiledOnPreRender(ctx) {
    jQuery(".csrHiddenField").closest("tr").hide();
}

 9. 使用sp.ui.controls.js文件来定义client chrome control，需要使用jQuery或MicrosoftAjax.js来支持：

// Prepare the options and render the control
// The Help, Account and Contact pages receive the 
//   same query string parameters as the main page
var options = {
    "appIconUrl": "../Images/AppIcon.png",
    "appTitle": "Basic tasks using the JSOM",
    "appHelpPageUrl": "Help.html?"
        + document.URL.split("?")[1],
    "settingsLinks": [
        {
            "linkUrl": "Account.html?"
                + document.URL.split("?")[1],
            "displayName": "Account settings"
        },
        {
            "linkUrl": "Contact.html?"
                + document.URL.split("?")[1],
            "displayName": "Contact us"
        }
    ]
};

var nav = new SP.UI.Controls.Navigation(
                        "chrome_ctrl_placeholder",
                        options
                    );
nav.setVisible(true);

效果为：

 

10. mapviewtemplate.js用来设置一个含有geolocation类型字段的视图，效果如下：

11.