{"id":2496,"date":"2016-07-18T14:48:49","date_gmt":"2016-07-18T12:48:49","guid":{"rendered":"https:\/\/sii.pl\/blog\/?p=2496"},"modified":"2023-08-18T11:39:28","modified_gmt":"2023-08-18T09:39:28","slug":"client-side-rendering-in-sharepoint","status":"publish","type":"post","link":"https:\/\/sii.pl\/blog\/en\/client-side-rendering-in-sharepoint\/","title":{"rendered":"Client Side Rendering in SharePoint"},"content":{"rendered":"\n

At this article I`d like to introduce Client Side Rendering (CSR) and how to use it on a real life example. Despite the fact that the CSR was introduced together with the SharePoint 2013 and have been making us happy with new UI possibilities for a few years already, it calls out questions. For example, developers are still using custom web parts to make customized list views. Instead of customizing standard SharePoint views with simple JavaScript.
Examples in topic are on typescript.<\/p>\n\n\n\n

Introduction:<\/h2>\n\n\n\n

What is the CSR? It is the client side JavaScript based html render. CSR gets JSON object from the server and renders markup into the DOM object, using internal mechanisms.
Interesting thing is that the new feature of 2013th version \u201cScript Editor\u201d web part works the same way. I`ll describe interesting possibilities of \u201cScript Editor\u201d web part at the next topic.
How CSR customization looks like? It has two events and a structure of render methods:<\/p>\n\n\n\n

    \n
  1. OnPreRender<\/li>\n\n\n\n
  2. RenderView\n
      \n
    1. RenderHeader<\/li>\n\n\n\n
    2. RenderBody\n
        \n
      1. RenderGroup<\/li>\n\n\n\n
      2. RenderItem<\/li>\n\n\n\n
      3. RenderField<\/li>\n<\/ol>\n<\/li>\n\n\n\n
      4. RenderFooter<\/li>\n<\/ol>\n<\/li>\n\n\n\n
      5. OnPostRender<\/li>\n<\/ol>\n\n\n\n

        How you can see from the events named OnPreRender and OnPostRender, those events are raised before and after render respectively. They are usually used for style modifications when full definition of render is not needed. However, the interesting functional is in methods, which names are starting from Render word. There are re-definable functions to render SharePoint list views. The most important thing is that SharePoint standard definition is fully replaced with the custom definition of the method. For example if you redefine the RenderBody method you will not able to call SharePoint definition anymore, as well as child methods for Group, Item and Field. These child methods will return empty string. It means the higher level of customization \u2013 the more stuff you have to redefine.
        To register your customization you have to call method:<\/p>\n\n\n

        \nSPClientTemplates.TemplateManager.RegisterTemplateOverrides(options);\n<\/pre><\/div>\n\n\n
        This method accepts the object with the following structure:<\/p>\n\n\n
        \nvar options = {\nOnPreRender: [(ctx) => { \/*prerender action*\/  }],\nTemplates: {\nHeader: (ctx) => { \/*Header HTML string*\/return ""; },\nBody: (ctx) => { \/*Body  HTML string*\/return ""; },\nView: (ctx) => { \/*View HTML string*\/return ""; },\nGroup: (ctx) => { \/*Group HTML string*\/return ""; },\nItem: (ctx) => { \/*Item HTML string*\/return ""; },\nFields: {\n"fieldInternalName": {\n"NewForm": (ctx) => { \/*new form view HTML string*\/return ""; },\n"EditForm": (ctx) => { \/*edit form view HTML string*\/return ""; },\n"DisplayForm": (ctx) => { \/*display form view HTML string*\/return ""; }\n}\n},\nFooter: (ctx) => { \/*Footer HTML string*\/return ""; }\n},\nOnPostRender: [(ctx) => { \/*postrender action*\/ }]\n};\n<\/pre><\/div>\n\n\n
        All object properties except On\u2026Render events are nullable, and if the value is not passed – then standard SharePoint method will be called.
        Contrary to the common opinion that the JSLink is not equal to CSR, SharePoint have options to register custom render script: JSLink, \u201cScript Editor\u201d web part next to View are the safest ways. You can use master page script link, custom action etc. but in this case you need to be sure that the “clienttemplates.js” SOD is loaded.
        Let`s look briefly to the JSLink syntax:<\/p>\n\n\n\n
          \n
        1. To specify the URL to the script you should use the following tokens:\n
            \n
          1. ~site \u2013 reference to the current SharePoint site (or \u201cWeb\u201d)<\/li>\n\n\n\n
          2. ~sitecollection \u2013 reference to the current SharePoint site collection (or \u201cSite\u201d)<\/li>\n\n\n\n
          3. ~layouts \u2013 version specific reference to the web application Layouts folder (so it will automatically swap out \/_layouts\/14 or \/_layouts\/15 for you)<\/li>\n\n\n\n
          4. ~sitecollectionlayouts \u2013 reference to the layouts folder in the current site collection (e.g. \/sites\/team\/_layouts\/15)<\/li>\n\n\n\n
          5. ~sitelayouts \u2013 reference to the layouts folder in the current site (e.g. \/sites\/teams\/subsite\/_layouts\/15)<\/li>\n<\/ol>\n<\/li>\n\n\n\n
          6. If you need to specify few JavaScript links at the same time than use \u201c|\u201d separator<\/li>\n<\/ol>\n\n\n\n
            We have a project, which is a small mail service with possibility to prepare the email content and send it to target audience. This solution contains two lists: \u201cNewsletter\u201d and \u201cNewsletter Contents\u201d.
            Newsletter – defines the mail header and the list of recipients. On a main view there should be a possibility to preview email body.
            Newsletter Contents \u2013 defines the list of containing contents with its own attachments and external references. There could be a few Contents for each \u201cNewsletter\u201d. Content should be created from Newsletter only.
            The functionality with email preview and blocking the item creation was developed using the CSR. For those purposes we defined two fields:<\/p>\n\n\n
            \n<Field ID="{4b5c1676-333a-4bd5-aefb-35e156765972}"\nSourceID="<%= sourceid %>"\nStaticName="MailexContentsStub"\nShowInNewForm="FALSE"\nShowInEditForm="FALSE"\nName="MailexContentsStub"\nJSLink="~sitecollection\/SiteAssets\/Mailex\/field.newsletter.content.js"\nDisplayName="Content Preview"\nRequired="FALSE"\nEnforceUniqueValues="FALSE"\nIndexed="FALSE"\nMaxLength="255"\nGroup="Blog Mail"\nType="Text"><\/Field>\n \n<Field\nType="Lookup"\nID="{225bfe7c-6043-4140-aa03-7dd2b17bba13}"\nJSLink="~sitecollection\/SiteAssets\/Mailex\/field.newsletterlookup.js"\nSourceID="<%= sourceid %>"\nStaticName="MailexContToNewsLook"\nName="MailexContToNewsLook"\nDisplayName="Newsletter"\nRequired="TRUE"\nEnforceUniqueValues="FALSE"\nList="<%= listid %>" WebId="<%= webid %>"\nShowField="Title"\nUnlimitedLengthInDocumentLibrary="FALSE"\nGroup="Blog Mail" ><\/Field>\n<\/pre><\/div>\n\n\n
            As you can see JSLink points to ~sitecollection, this token is replaced with SPSite server relative URL by SharePoint automatically. Please take a look to SourceID, List, WebId attribute values: this syntax is used for auto fill values using the underscore.js template during the deployment time. Underscore.js is quite useful library. With specific tag, you can insert the normal text as well as executable code and html escaped text. More details by link http:\/\/underscorejs.org\/#template
            Let\u2019s take a look to real life view:<\/p>\n\n\n\n
            \"newsletter<\/a><\/figure>\n\n\n\n
            When you chose the single list item, custom ribbon action is activated. On click \u201cAdd Content\u201d button, the NewForm modal dialog for Newsletter Content will be opened. NewsletterId of the selected item will be passed to this dialog box via URL. The NewForm contains \u201cNewsletter\u201d field with CSR (you can find xml definition of the field earlier).<\/p>\n\n\n\n
            \"Newsletter<\/a><\/figure>\n\n\n\n
            After item creation we return to main view of Newsletter list, and click on Contents link, it is second CSR field. This is a stub field, which is hidden in all forms except display form. On click would be opened modal dialog with email preview:<\/p>\n\n\n\n
            \"Newsletter<\/a><\/figure>\n\n\n\n
            In case if you would like to create new item for newsletter content via standard SharePoint New Item button you will see following error:<\/p>\n\n\n\n
            \"Newsletter<\/a><\/figure>\n\n\n\n
            Implementation:<\/h2>\n\n\n\n
            So, now I`ll describe how CSR script was created for the Newsletter lookup field. The content preview was made similar way, but was much more simple than this lookup.
            How it was developed: I`ve created TS file field.newsletterlookup.ts, which contains all logic around this field modification and validation. Let\u2019s take a look part by part:<\/p>\n\n\n\n
              \n
            1. Template registration: <\/li>\n<\/ol>\n\n\n
              \n$(document).ready(() => {\nSP.SOD.executeFunc("clienttemplates.js", "SPClientTemplates", function () {\nSPClientTemplates.TemplateManager.RegisterTemplateOverrides({\nTemplates: {\nFields: {\n'MailexContToNewsLook': {\n'EditForm': NewsletterLookupFieldCsr.newsletterNewAndEdit,\n'NewForm': NewsletterLookupFieldCsr.newsletterNewAndEdit\n}\n}\n}\n});\n});\n});\n<\/pre><\/div>\n\n\n
              This template is simple and we can use the single render template for New and Edit forms. DisplayForm will show the normally rendered lookup field. The template building module has an interface:<\/p>\n\n\n
              \nexport function newsletterNewAndEdit(ctx) : string\n<\/pre><\/div>\n\n\n
              The input parameter ctx is the current CSR context generated on server side. Context \u201cctx\u201d contains information regarding the list, item and rendering methods. Render function returns string value with field value wrapped in html markup. However, we need to do some more operations to make render mechanism working correctly. We need to register validators and define post back functions. So let\u2019s take a look closely:<\/p>\n\n\n
              \nconst formCtx = SPClientTemplates.Utility.GetFormContextForCurrentField(ctx);\nif (formCtx == null || formCtx.fieldSchema == null)\nreturn "";\nconst validators = new SPClientForms.ClientValidation.ValidatorSet();\nvalidators.RegisterValidator(new NewsletterLookupFieldValidator());\nformCtx.registerClientValidator(formCtx.fieldName, validators);\nformCtx.registerValidationErrorCallback(formCtx.fieldName, newsletterLookupOnError);\nformCtx.registerGetValueCallback(formCtx.fieldName, () => {\nvar el = document.getElementById(readField);\nif (typeof el != "undefined" && el != null) {\nconst lookUpVal =\n(<HTMLInputElement>document\n.getElementById("inpNewsletterHiddenValue ")).value;\nif (!lookUpVal || lookUpVal === "none") {\n} else {\nreturn lookUpVal;\n}\n}\nreturn null;\n<\/pre><\/div>\n\n\n
                \n
              1. Custom validation. We will be using field validator to implement restrictions which won\u2019t allow user to create an item directly from the list:<\/li>\n<\/ol>\n\n\n
                \nconst validators = new SPClientForms.ClientValidation.ValidatorSet();\nvalidators.RegisterValidator(new NewsletterLookupFieldValidator());\nformCtx.registerClientValidator(formCtx.fieldName, validators);\n<\/pre><\/div>\n\n\n
                Method RegisterValidator accepts new instance if an object with Validate method. In our case this object is NewsletterLookupFieldValidator:<\/p>\n\n\n
                \nexport class NewsletterLookupFieldValidator {\npublic Validate() {\nlet isError = false;\nlet errorMessage = "";\nconst el = document.getElementById("inpNewsletterHiddenValue");\nif (typeof el != "undefined" && el != null) {\nconst lookUpVal = (<HTMLInputElement>el).value;\nif (!lookUpVal || lookUpVal === "none") {\nisError = true;\nerrorMessage = "Item cannot be created\/updated without related Newsletter.\nPlease create an item via Newsletter ribbon control";\n}\n} else {\nisError = true;\nerrorMessage = "Html element not found";\n}\nreturn new SPClientForms.ClientValidation.ValidationResult(isError, errorMessage);\n}\n};\n<\/pre><\/div>\n\n\n
                As you can see this method returns the ValidationResult object, which later will be passed into the Validation callback. Usually validation method checks the user actions on UI. In our case we will just check if the Newsletter ID is set.<\/p>\n\n\n\n
                To register Validation Callback, the method which will be called on validation error, you need to call:<\/p>\n\n\n
                \nformCtx.registerValidationErrorCallback(formCtx.fieldName, newsletterLookupOnError);\n<\/pre><\/div>\n\n\n
                Callback method definition is:<\/p>\n\n\n
                \nfunction newsletterLookupOnError (error) {\ndocument.getElementById("spnError").innerHTML = `<span\nrole='alert'>${error.errorMessage}<\/span>`;\n}\n<\/pre><\/div>\n\n\n
                This method returns html markup with an error text passed from Validation method to ValidationResult constructor.<\/p>\n\n\n\n
                <\/div>\n\n\n\n
                The next step is to define Get Value callback. This method gathers value from your custom markup and returns it in SharePoint format. In our case it is lookup value in format \u201cid;#title\u201d.<\/p>\n\n\n
                \nformCtx.registerGetValueCallback(formCtx.fieldName, () => {\nvar el = document.getElementById(readField);\nif (typeof el != "undefined" && el != null) {\nconst lookUpVal =\n(<HTMLInputElement>document\n.getElementById("inpNewsletterHiddenValue ")).value;\nif (!lookUpVal || lookUpVal === "none") {\n} else {\nreturn lookUpVal;\n}\n}\nreturn null;\n});\n<\/pre><\/div>\n\n\n
                After definition of all post render actions, we will be rendering current value for EditForm and for set default value:<\/p>\n\n\n
                \nlet currentValue = "none";\nlet curDisplayName = "none";\nconst lookupValues = ctx.CurrentItem["MailexContToNewsLook"];\nif (lookupValues != null && lookupValues.length > 0) {\nconst arr = lookupValues.split(";#");\ncurDisplayName = arr[1];\ncurrentValue = lookupValues;\n}\nconst html = `<span><span><input type="hidden" id="inpNewsletterHiddenValue" value="${currentValue}"\/><\/span><span class="ms-standardheader" id="spanNewsletterValue">${curDisplayName}<\/span><br\/><div id="spnError" class="ms-formvalidation ms-csrformvalidation"><\/div><\/span>`;\n<\/pre><\/div>\n\n\n
                In case of a NewForm we have to check if there is Newsletter ID passed via URL from \u201cAdd Content\u201d custom ribbon action.<\/p>\n\n\n
                \nif (lookupValues == null || lookupValues.length === 0) {\nconst regex = new RegExp(`[\\?&]newsletterId=([^&#]*)`);\nlet curId = regex.exec(location.search);\ncurId = (curId === null ? null : decodeURIComponent(curId[1].replace(\/\\+\/g, " ")));\nif (curId != null && curId.length !== 0) {\nretrieveNewData("inpNewsletterHiddenValue", , curId);\nvar clientContext = new SP.ClientContext();\nvar targetList = clientContext.get_web().get_lists().getByTitle("Newsletter");\nvar targetListItem = targetList.getItemById(curId);\nclientContext.load(targetListItem);\nclientContext.executeQueryAsync(() => {\n$(`#inpNewsletterHiddenValue`)\n.val(targetListItem.get_id()+";#"+ targetListItem.get_item("Title"));\n$(`#spanNewsletterValue`).text(targetListItem.get_item("Title"));\n}, () => {\nconsole.log("Data retrieve failed");\n});\n}\n \n}\n<\/pre><\/div>\n\n\n
                If the field doesn`t have any value, or \u201cnewsletterID\u201d have not been passed via url, then the \u201cnone\u201d text would be rendered. The value for hidden input inpNewsletterHiddenValue will be set \u201cnone\u201d as well. Now when you click Save button, a method Validation will raise an error with text: “Item cannot be created\/updated without related Newsletter. Please create an item via Newsletter ribbon control” and Validation will not be passed.
                I`ve mentioned two customized fields at the beginning, but the second field is quite simple. There is no validators and \u201cget value\u201d postback. There is only Link markup generator, but under the hood, there are some actions to retrieve list items data and render it into html using underscore.js.<\/p>\n\n\n\n
                Conclusion:<\/h2>\n\n\n\n
                To summarize the topic values I`d say CSR it is the very flexible and powerful tool and a kind of official Microsoft hack for SharePoint UI. Now you are able to:<\/p>\n\n\n\n
                  \n
                1. Customize views without involving the SharePoint Designer.<\/li>\n\n\n\n
                2. Create dependent fields<\/li>\n\n\n\n
                3. Customize validation<\/li>\n\n\n\n
                4. Change standard controls to something interesting like a progress bar or slider<\/li>\n<\/ol>\n\n\n\n
                  All these operations are compatible with SharePoint online and On-premise.<\/p>\n\n\n\n
                  In next topic I`ll describe some interesting features with Script Editor web part.<\/p>\n\n\n
                  \n            \n
                  \n    \n
                  \n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n    <\/div>\n    \n
                  \n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n            
                  \n            \n\n
                  <\/div>\n        <\/div>\n    <\/div>\n<\/div>\n                \n\n
                  \n            4.3\/5 ( votes: 3)    <\/div>\n    <\/div>\n","protected":false},"excerpt":{"rendered":"
                  At this article I`d like to introduce Client Side Rendering (CSR) and how to use it on a real life … Continued<\/a><\/p>\n","protected":false},"author":81,"featured_media":537,"comment_status":"open","ping_status":"open","sticky":false,"template":"","format":"standard","meta":{"_acf_changed":false,"_editorskit_title_hidden":false,"_editorskit_reading_time":0,"_editorskit_is_block_options_detached":false,"_editorskit_block_options_position":"{}","inline_featured_image":false,"footnotes":""},"categories":[1320],"tags":[1345,1476,1338,1411,1413,1474,1475],"class_list":["post-2496","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-hard-development","tag-sharepoint-en","tag-csr-en","tag-javascript-en","tag-sharepoint-2013-en","tag-sharepoint-2016-en","tag-typescript-en","tag-underscore-js-en"],"acf":[],"aioseo_notices":[],"republish_history":[],"featured_media_url":"https:\/\/sii.pl\/blog\/wp-content\/uploads\/2015\/10\/16_SharePoint_v2.jpg","category_names":["Hard development"],"_links":{"self":[{"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/posts\/2496"}],"collection":[{"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/users\/81"}],"replies":[{"embeddable":true,"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/comments?post=2496"}],"version-history":[{"count":2,"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/posts\/2496\/revisions"}],"predecessor-version":[{"id":23588,"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/posts\/2496\/revisions\/23588"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/media\/537"}],"wp:attachment":[{"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/media?parent=2496"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/categories?post=2496"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/sii.pl\/blog\/en\/wp-json\/wp\/v2\/tags?post=2496"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}