SharePoint gives new capabilities that developers can use to do same tasks required in previous versions of SharePoint using client side technologies. The main capability introduced in SharePoint 2013 is CSR (Client Side Rendering). The most common used method for CSR way is to manipulate users data for fields or list views.. But what about forms?
Someone is going to say: “Yes, SharePoint provides JS Link property for list forms as well, so what’s new with it?” Well, there’s more into it. Let’s see what can be done in list forms and to what extent we have the flexibility to do the forms we want.
Here we have a list called Customers, with a new form that looks like this:
Now, we want to make this look different, so we’ll be using JS Link for that. If you edit the newform page, and edit the web part:
Then go to Miscellaneous, you will find three important properties there:
- Form Template Name
- JS Link
- CSR Render Mode
We know that with JS Link we will be able to add a JS file and manipulate our form’s design. We also know that CSR Render Mode being set to standard it tells SharePoint to renders the form using CSR, and setting it to Server Render will make it depend on XSLT for that. But what about Form Template Name and its ListForm value?
If you had experience with SharePoint customization from previous versions specially for forms, you know that SharePoint uses technique called: Rendering Templates. Which is a group of predefined templates SharePoint has and uses them to render its pages and forms. If you have an on premises environment, you can go to this path: SharePoint Hive\TEMPLATE\CONTROLTEMPLATES, you will find a file called: DefaultTemplates.ascx:
If you open that file, you will find many controls with the tag: <SharePoint:RenderingTemplate.. . If you search for ListForm, you will find that it’s actually a rendering template that SharePoint uses to render its forms. But the good thing to know is, you can use another value which is CSRListForm. But what’s the difference?
The difference is that ListForm renders everything for you from SharePoint, like the layout for the form, the label names and so on, so if you need to use JS Link to style your list forms while you are using ListForm rendering template, you would need to use jQuery to restructure your HTML. So what if we use CSRListForm instead? Your list form would look like the following:
It will only render the fields for you, no labels, no buttons, no spaces between fields, nothing.. just fields. So you will have a clean output that you can play with in JS Link as much as you like! That’s neat!
Now let’s add a JS Link property to a .js file and try to style our form, there’s a file that my friend Muawiyah Shannak created and posted on MSDN, you can download the JS Link file here: https://code.msdn.microsoft.com/office/CSR-code-samples-11-Fully-54ebcaa6
Here we are declaring the objects necessary to form our view:
|
|
var formTemplate = {}; formTemplate.Templates = {}; formTemplate.Templates.View = viewTemplate; |
Inside the viewTemplate function we have the following 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 |
function viewTemplate(ctx) { var formTable = "".concat("<table width='100%' cellpadding='5'>", "<tr>", "<td><div>Title</div></td>", "<td><div>{{TitleCtrl}}</div></td>", "<td><div>Date</div></td>", "<td><div>{{DateCtrl}}</div></td>", "</tr>", "<tr>", "<td><div>Category</div></td>", "<td><div>{{CategoryCtrl}}</div></td>", "<td><div>Active</div></td>", "<td><div>{{ActiveCtrl}}</div></td>", "</tr>", "<tr>", "<td></td>", "<td><input type='button' value='Save' onclick=\"SPClientForms.ClientFormManager.SubmitClientForm('{{FormId}}')\" style='margin-left:0' ></td>", "</tr>", "</table>"); formTable = formTable.replace("{{TitleCtrl}}", getSPFieldRender(ctx, "Title")); formTable = formTable.replace("{{DateCtrl}}", getSPFieldRender(ctx, "Address")); formTable = formTable.replace("{{CategoryCtrl}}", getSPFieldRender(ctx, "VIP")); formTable = formTable.replace("{{ActiveCtrl}}", getSPFieldRender(ctx, "Country")); formTable = formTable.replace("{{FormId}}", ctx.FormUniqueId); return formTable; } |
As can be seen, we’re constructing the HTML for our form, for this article and on MSDN, we made it static just for learning and explanation purpose. You can do whatever technique you prefer to form the HTML.
Three things to note about this code:
- Note how we have {{placeholders}} for each field we want to add in our HTML.
- Note also the getSPFieldRender function, I’ll explain that later on.
- The input button has an onclick function = SPClientForms.ClientFormManager.SubmitClientForm(‘{{FormId}}’) . This will allow us to use the out of the box capabilities to leverage the submit action and handling validations in the form.
Back to getSPFieldRender, this will go look into the form for each field by its internal name, and will get this field’s HTML, which will be replaced instead of the place holders such as {{TitleCtrl}}. This happens by using the CurrentFieldSchema and drilling down to the Field’s HTML from the ctx.Templates.Fields, As shown below:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 |
function getSPFieldRender(ctx, fieldName) { var result = ctx.ListSchema.Field.filter(function( obj ) { return obj.Name == fieldName; }); ctx.CurrentFieldSchema = result[0]; ctx.CurrentFieldValue = ctx.ListData.Items[0][fieldName]; return ctx.Templates.Fields[fieldName](ctx); } |
Now, when apply this JS Link to our list form, SharePoint will render the fields, and place them instead of our placeholders, it would look like below:
Without using any jQuery hacks, you can now apply your designs to your list forms with the use of CSRListForms.
Hope that gave more understanding to List Forms and CSR.
