First things first, I want to apologize, because what I’m going to build in this post is pretty hideous. I’m going to introduce the concept of hooking up SharePoint CSR by type, rather than by internal field name (as most examples show). In this post, I’m going to show how to do CSR by Type, meaning override all fields of a given SPFieldType.
By way of background, yesterday I was trying to override the Client-side Rendering (CSR) of a Url field to allow it to take non-standard protocols like notes://. I didn’t feel like creating a site column so I applied it to the OOB site column called Url. So I setup my overrides like so:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | // override the render for the field called Url? var overrides = { Templates: { Url: { NewForm: editOverride, EditForm: editOverride, DisplayForm: displayOverride, View: displayOverride, } }, // insert the css OnPostRender: postRender, }; // register the template overrides, and to keep it simple, ignoring MDS SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrides); |
Here I’m overriding the rendering for the field called Url in all forms and views, right? Not so fast sparky! This worked a little too well. My override was getting called for other fields of type SPFieldUrl on the page that weren’t named Url. Ugh! Stepping through clienttemplates.js in the debugger, it quickly became apparent what was going on. In the fields object, you can specify CSR by internal field name, like I’ve been doing in previous posts in this series, but you can also specify CSR by type of field (using the client-side field type, so for instance Text for SPFieldText). This replaces the default rendering for all fields of that type.
That’s actually pretty cool, but the problem with it is that if you have a field whose internal name is the same as a field type, there is no way for you to override just that field. Bad Microsoft, programmer no donut! The rest of this post is going to be a quick demo I put together to demonstrate this functionality. I haven’t seen anything in the documentation for CSR, or any examples, that explain this functionality. Of course, the documentation for CSR is pretty thin.
I’m going to override the rendering for all fields of type SPFieldText. To do that, I’ve implemented the following CSR code:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 | (function() { // if we're not on a form, get out of dodge if (typeof(SPClientTemplates) === "undefined") return; /* * Handle rendering of text fields on display forms and views. */ var displayOverride = function(ctx) { var value = ctx.CurrentItem[ctx.CurrentFieldSchema.Name]; return "<div class='blinking'>" + (value.length > 0 ? value : " ") + "</p>"; } /* * Handle rendering of text fields on new and edit forms. */ var editOverride = function(ctx) { var formCtx = SPClientTemplates.Utility.GetFormContextForCurrentField(ctx); var id = formCtx.fieldName; var value = ctx.CurrentItem[id]; formCtx.registerGetValueCallback(formCtx.fieldName, function() { return document.getElementById(formCtx.fieldName + "_TxtBox").value; }); return "<input class='blinking blinkingTxtbox' name='" + id + "' id='" + id + "_TxtBox' value='" + value + "'/>"; } /* * Insert some css to get those amazing technicolor text boxes. */ var cssInserted = false; var postRender = function(ctx) { if(!cssInserted) { cssInserted = true; var css = document.createElement("style"); css.type = "text/css"; css.innerHTML = ".blinking {border-left: 1px solid red !important; border-top: 1px solid green !important; border-right: 1px solid yellow !important; border-bottom: 1px solid blue !important; color: red !important; animation: blinker 1s linear infinite; padding: 3px;} .blinkingTxtbox {width: 386px;} @keyframes blinker { 80% {opacity: 0} }"; document.body.appendChild(css); } } // construct the overrides var overrides = { Templates: { Fields: { // normally, Text would be the internal name of a field, but here it is the type of a field, // which makes this override the default rendering for all fields of that type Text: { NewForm: editOverride, EditForm: editOverride, DisplayForm: displayOverride, View: displayOverride } } }, // insert the css OnPostRender: postRender }; // register the template overrides, to keep it simple, ignoring MDS SPClientTemplates.TemplateManager.RegisterTemplateOverrides(overrides); })(); |
And because my CSS is scrunched up in a single line of code, I’ve broken it out here and formatted it for better readability:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 | .blinking { border-left: 1px solid red !important; border-top: 1px solid green !important; border-right: 1px solid yellow !important; border-bottom: 1px solid blue !important; color: red !important; animation: blinker 1s linear infinite; padding: 3px; } .blinkingTxtbox { width: 386px; } @keyframes blinker { 80% { opacity: 0 } } |
There’s nothing special about this CSR, it’s just using the same techniques I’ve been using throughout this series. The only difference is that it’s overriding Fields.Text, which isn’t the name of a field but rather the client-side name of a field type (SPFieldText).
As usual, I still need to get the JavaScript injected into the page. To do that I’m going to set the JSlink property of the Title field. Since every list has a title field, this effectively overrides the rendering of text fields in every form or view in the site collection. If you haven’t read through this series, you can accomplish this using the utility page from the previous post Setting the JSLink Property of a Field Using JavaScript.
With that done, if I visit a contacts list in my site collection, I am greeted with this lovely display:
Now kids, don’t try this at home, this is for demo purposes only. The forms look similar, but I haven’t shown them here because I really don’t want to be held responsible for giving my readers headaches, or worse yet seizures.
Specifying CSR by type is a cool technique, but with great power comes great responsibility. For instance, my first attempt screwed up the callback to registerGetValueCallback, so it always returned an empty string. This caused the form to fail to submit, because the required field title didn’t have a value, but since I haven’t implemented validation in my simple example, no error message is displayed to the user. You just click the button and nothing happens. I probably don’t need to tell you this, but you’re not going to win any medals for breaking every form in your site collection. I’ve fixed that of course, but this still isn’t a complete example. At a bare minimum, it should call registerValidationErrorCallback to show validation error messages to the user.
The takeaways from this are:
- You can override the rendering by registering CSR by type or internal field name.
- If the type and the internal field name are the same, that’s a problem, so don’t do that.
- And finally, don’t use OOB site columns that have an internal field name that is the same as a field type in any CSR solutions.
One final caveat is that while this CSR did override the title field in my contacts list, in SharePoint online it did not override the title field in several other lists. It does override all other text fields in all lists. I’m not sure why, I’d need to step through clienttemplates.js again to figure it out. I haven’t seen that behavior on any on prem version of SharePoint.
This post started off as an answer to a question on StackExchange, but I figured it was worth expanding on a bit.