Category Archives: Client-Side Rendering (CSR)

JS Link – Using CSR for KPIs

OK. Someone asked me today if CSR and JS Link can be used incorporate KPIs into a list view. The answer of course is ‘yes’. This is a wonderful example of how CSR can be used. Smile

Background: If you’re wondering what a ‘KPI’ is – it’s a ‘key performance indicator’. You can find more about them here: http://en.wikipedia.org/wiki/Performance_indicator What we’re talking about specifically in this case is a visual KPI in a SharePoint list view – something that can be used as a quick visual cue as to what the data is showing.

If you’re wondering what CSR and JS Link are referring to, take a peek at my “JS Link – Hello World” article.

With all that settled, here’s a quick example of one way KPIs could be incorporated into a list view using CSR and JS Link:

Create a list (yes, you can use an existing list).
Add or identify a column that’s going to be used as a value to test.
Add or identify a column for where the KPI indicator can be displayed – a graphic will override whatever data might be in this field. The title of the column can be useful to indicate which KPI is being displayed…
Identify the locations of graphics to be used as the KPI indicators. I put mine in the Site Assets library for this example, but they could be stored just about anywhere.

Here’s the sample JavaScript:

Note: You can update the fully qualified links to the image to relative links: src=”/TeamSite/CSR/…” (still need the rest of the URL, but dropping the beginning part)

In the example code, we’re checking the value of one field and displaying the image in an override of a second field.

Again, this is an extremely simple example – the logic for the KPI could be much more complicated as needed. There could be one or more KPIs per item. Lots of ways to improve on the concept.

The example ends up looking something like this:

NOTE: For this quick and dirty example I created a field in the list that is essentially used only as a field to be overridden with an image. If I want to make the solution cleaner and more UX friendly I could do an Item override which would allow me to skip adding the new ‘container’ field. I could just bake the image into the rendered HTML directly.

Reference to where the images came from: http://commons.wikimedia.org/wiki/Category:Light_icons

Another much more complicated example:
http://www.connectorman.com/jslink-code-kpis-sharepoint-2013-2/

Client-Side Rendering (CSR) demystified – Slides

At SPC14 – the SharePoint Conference 2014 – I initially presented a session on Client-Side Rendering in SharePoint 2013 as implemented using JS Link through the web interface. CSR and JS Link using uploaded JavaScript files and the JS Link web part property pointed at the appropriate JavaScript files – to be differentiated from JS Link baked into managed code.

The recording and slides for the SPC session are available here – on Channel9: http://channel9.msdn.com/events/SharePoint-Conference/2014/SPC318

This content has also since been presented (in slight variations of the original) at a few SharePoint Saturday events.

JS Link – Highlighting a Row with CSR

One conditional formatting scenario in SharePoint 2010 and SharePoint Designer 2010 was to highlight a row in a list view based on a rule: data within the item/row. SharePoint Designer 2013 unfortunately does not have the same design view available, so we need to use some relatively simple code to get the same results. This article discusses one method to get the same results using SharePoint 2013 with Client-Side Rendering (CSR) and the JS Link web part property.

Referring back to a few of my other posts you can get an idea of the general approach using CSR here:

When creating the JavaScript file this time we aren’t doing any Field or Item overrides, but we are using the PostRender functionality:

OverrideCtx.OnPostRender = {

As the name describes, we’re tweaking the page output after the rest of the page has been rendered. Using Field overrides we could alter the formatting of text, but not cells and wouldn’t have access to the row either. Using the Item override we could build the row from scratch and highlight the row, but it would take a lot more work rebuilding the view when we can just use the PostRender method to tweak the existing view.

I won’t get into all the JavaScript details but want to highlight what’s important to replicate this functionality on your own. The code essentially steps through each item/row in the table and runs the logic on each item.

There are only a few snippets you need to customize to fit your scenario:

if (listItem.Priority == “(1) High”) {

The code above is your condition / rule. ‘Priority’ is the column you’re checking the value on – remember that ‘Priority’ is the internal name of the column. You can use any column that’s included in the view for your rule criteria.

row.style.backgroundColor = “rgba(255, 0, 0, 0.5)”; //red

This (above) is setting the row background color. You can set whichever color you need. You can have multiple rules checking different rows and applying various colors if you wish.

OK! Once the JavaScript is written and uploaded to the site (see other posts for details) and the JS Link property is set, if everything is working the list should now show a highlighted row for data that matches the rule:

Using the PostRender approach makes highlighting an entire row pretty easy. If you wanted to highlight a specific cell, it would be possible but would take some more code (we’ll show that another time) to get the right column selected. It’s not as easy as just calling out the column/field name. Depending on what you’re trying to accomplish on the cell/field level, that kind of change might be easier using the Field override.

Thanks again to Jon Campbell (MS), Raymond Mitchell and Phil Jirsa for hammering through much of the JavaScript details on this one. Jon clued us into some of these JS Link innerds back when he was on the SharePoint team. 🙂

JS Link – CSR View Conditional Formatting

This post builds on the JS Link – CSR Simple View Field Formatting post.

If you can format a single field as was done in the previous example, it’s not a big step from there to using conditional formatting.

In SharePoint Designer (pre-2013) one of relatively easy yet powerful features was conditional formatting – the ability to dynamically change how content was displayed based on rules. In the last post we went over how to do simple formatting, in this post we’ll review how to incorporate some simple rules or conditions.

In the previous example we bolded everything in the Issue Status field.

In this example we’ll ‘conditionally’ select which items are bolded based on data values for each item.

We’ll start with a couple of individual fields and go from there. For this example and similar to the last post, I created a page in the Site Pages library and added the Office Issues web part to the page. I’ll be setting the JS Link property of the web part here in a few steps.

In this post we’re adding three concepts:

JavaScript – Calling a function.
If you are a JavaScript developer this concept isn’t really even worth mentioning. If you are not a developer, we’re moving the code around a little bit to keep it organized, easier to read, etc…‘Status’:{‘View’: ConditionalStatus},
In this line rather than setting the value of the field outright like we did with simple field formatting, we’re calling a function ‘ConditionalStatus’ where addition work is being done.
Checking for the ‘condition’ or rule.
Without getting into all the JavaScript details, what we’re doing in the function is checking the value of the ‘Issue Status’ field and either making the contents bold, or leaving them in the default format.if (ctx.CurrentItem.Status == “Active” ) {
Building the HTML for what is displayed or rendered in the web part on the page.In this example we’re just using a the HTML tags necessary to bold the content being displayed. You could use virtually any HTML or CSS you wanted when it comes to formatting the data:ret = “<b>” + ctx.CurrentItem.Status + “</b>”;
You should also note the way we set up the data. The HTML and field data need to be built into a string – which is different than the way we did it in the previous post.

The full sample code can be found HERE.

The completed file is then uploaded to your chosen location: Master Page Gallery in this case. The web part JS Link property is configured to point to your JavaScript file:

~site/_catalogs/masterpage/[yourFileName].js

Notes:

You are not limited to pairing the conditional field with the field that is custom rendered.
If Issue Status is ‘Active’, bold the Status field…
You can just as easily define a rule for the Title field to check the value of the Issue Status field.
If the Issue Status field is ‘Active’, bold the Title field…
You can also combine rules into more complicated criteria
If Issue Status is ‘Active’ and Priority is ‘High’, then bold the Title field…

Rather than customizing how each field is displayed separately, you can use a different override – the Item override – to customize each field or how the entire item is displayed. This will be covered in a separate post.

SharePoint Conference 2014 – Sessions Up

Sessions have been posted for the next SharePoint Conference 2014 in Las Vegas.

http://www.sharepointconference.com/content/sessions

See what sessions you want to attend and get registered now!

I’ll be doing a session on Client Side Rendering (CSR) again if you missed it last time. Smile #SPC318.

See you there!

SharePoint Fest DC – PWR104 – Customizing SharePoint 2013 Sites and Pages

The following is a link to the slides from today’s session on (mostly) CSR and JSLink within SharePoint 2013.

Much of the CSR / JSLink content and instruction can also be found in the blog post found here:
http://www.idubbs.com/blog/2012/js-link-for-sharepoint-2013-web-partsa-quick-functional-primer/

JS Link for SharePoint 2013 Web Parts–A Quick Functional Primer

JS Link is a new web part property in many SharePoint 2013 web parts. It allows users and developers to create Client-Side Rendering (CSR) solutions within SharePoint 2013. In other words, it allows alternate formatting, data and functionality to be manipulated within a web part. It is one approach that will help replace the data view web part (DVWP) functionality that was used in SharePoint 2010 and SharePoint Designer 2010.

For example, CSR scenarios can edit how specific fields are displayed, how whole web parts are formatted and what functionality is available. And these are just a few simple examples. There is a lot of potential for what can be done. My session at SPC12 just scratched the surface while others dug much deeper.

Something to note is that using JS Link to implement CSR functionality is easy and reversible. If you don’t like what it’s doing to your web part you can easily change the JS Link property back (blank it out) and your web part will go back to it’s default format.

The CSR approach is more developer-focused than power user-focused. There are, however, a few simple things that can be done that I think will be accessible to power-users that have some comfort level with code, specifically JavaScript, HTML and CSS.

So, here are the main components you need to make CSR work with out-of-box web parts – nothing fancy – using JS Link in SharePoint 2013:

Create a JavaScript override file
Upload the JavaScript file to the Master Page Gallery
- Set the content type and properties of the file in the Master Page Gallery
Set the JS Link property of the web part to point to the JavaScript file

Sounds easy enough, but there are a few details to sort out to get everything synced up. Additional details for each step are listed below:

Create the JavaScript file
In these examples, JavaScript is being used to override different things – how data is displayed and what content is displayed. For starters we’ll override a specific field in a view.

During my session at the SharePoint Conference (SPC12) I used a few simple examples that are a good starting point. EXAMPLE JS FILES

In the first example, we get everything in place and make sure that it’s working. We start with a standard view (AllItems) that shows text fields, and then use the JS Link functionality to override a single column – displaying different text than came with the view. We are replacing whatever the ‘MoreText’ column contained with the word ‘Animal’.

As the notes in the sample script mention, the Fields override works specifically with individual fields. You can specify a single field, or multiple fields. For each field (column) override, you need to identify the field being overridden and the replacement value.

When identifying the field name, take note that you need to use the internal name for the column, which may not be the same name that is displayed. In some cases this is true, but not all. See my post on finding the internal column name.

The ‘View’ component of the command is in reference to the type of template being overridden – in our case the view. There are also options for the NewItem, EditItem and DisplayItem forms, but we won’t cover them in this article.

The last piece of the command for each field is the override value for the field. This can be a static value – as in the first example – a variable, or HTML and the value, allowing you to style the value. You can also call a function within the script to do more complicated logic – such as conditional formatting – but for the field.

Note: The following example code is shown with the Before and After output of the sample web part. The changes will not go into effect until you’ve put all the pieces in place – the steps which are listed after the sample images.

Example 1: Uses a static value to override the field value. ‘Animal’ will replace the ‘MoreText’ field value for each list item in the view.

Before:

After:

Example 2: Displays the true value of the MoreText field, but formats it (bold) by wrapping it in an HTML tag.

Before:

After:

Example 3: Calls a function that formats the value that overrides the field data. In this case it uses a conditional to determine what data is displayed. This could just as easily be used to implement conditional formatting for the field by keeping the field data as in Example 2, but formatting it differently using HTML tagging.

Before:

After:

Example 4: Uses a different override. This example uses the Item override instead of the Field override. Using the Item completely overrides the web part and requires the Header and Footer overrides as well. In the example here, the data is displayed in an HTML list where the open tag is in the header and the closing tag is in the footer. Each item is then an item in the list.

Before:

After:

One other note on the code. We aren’t getting into details with these settings, but a few of the sample scripts also include settings for BaseViewID and ListTemplateType. These settings are not required, but if you are using JS Link on a page that has more than one view, these properties control which web parts are affected by the JavaScript code.

BaseViewID is the view ID for the list with 1 being the AllItems view.

ListTemplateType is the ID for the type of list template is used such as Links List, Task List, Custom List, etc. A list of these types in 2013 can be found here:
http://msdn.microsoft.com/en-us/library/microsoft.sharepoint.client.listtemplatetype(v=office.15).aspx

Upload it to the Master Page Gallery

The script files need to be uploaded to a place where they can be accessed by the web part. Depending on what version of SharePoint you’re using and what your scope is, you will need to determine the best location for the scripts. In our case we used Office 365 for a test bed and only want to use the scripts within our site collection, so we are uploading the files to the Master Page Gallery.

As each file is uploaded, the content type of the file will need to be changed to ‘JavaScript Display Template’ and the required fields will need to be completed.

In our examples, the Target Control Type is ‘View’.

The Standalone value is ‘Override’.

And the Target Scope is the relative URL of the site collection we’re customizing in the format: ‘/sites/d1’.

For our example, upload each of the 4 sample files so that you can see the different examples at work.

Add the JS Link property that points to the JS file

Finally, edit the web part properties you are trying to edit. This may be web parts on a web part page, or a web part on a standard view page. Edit the page, then the web part. Expand the Miscellaneous section and edit the JS Link property using the following sample format to point to the location of the JavaScript file you are using for the CSR override:

~site/_catalogs/masterpage/csr_overridable_demo1.js

Save your changes. If everything is working, the changes should be immediately visible. If you still need to edit the JavaScript to match your specific column or example, edit the file using SharePoint Designer.

Edit the files using SharePoint Designer 2013

Developers have a number of code editing tools at their disposal and can use Visual Studio or others. Non-developers can use SharePoint Designer 2013 to view and edit the JavaScript once it has been uploaded to the site.

If you haven’t already edited the files to match your specific list column names, start SharePoint Designer and open the site collection where you are doing your testing.

From SPD you can edit and save your JavaScript files live. After you make a change to the JavaScript file, refresh the browser page and your changes should be reflected – assuming everything is correct. Smile

Wrap-up

Sorry for such a short and unpolished post – there is a LOT more to talk about regarding JS Link and SharePoint 2013 – but I wanted to get this out for people that attended my #SPC064 session at #SPC12 or who started hearing the rumblings about JS Link this week while at the conference. Hopefully this allows you to get started playing around with the power of JS Link.

Lots more to come!

Notes:

JS Link is not only used in web parts, but can also be set and used when creating custom apps, etc. This post is just covering the specific example when using the web part property.
Be sure to take a look at the HTML that is produced by the page once you have your CSR in place. Some approaches in the CSR may not jive well with the existing page code. You want to avoid conflicting tags, etc.
JS Link override will not work if the form has been edited in SPD.

Finding Internal Names for SharePoint List Columns

The average user usually doesn’t need to care about ‘internal’ naming on SharePoint lists. They just need to work. But as you start to delve into some customization approaches, trying to piece some details together behind the scenes a bit, you may need to know internal names.

What are ‘internal’ names? They are one of the IDs used by the SharePoint system (other than GUIDs) to refer to columns, fields, etc. They don’t necessarily align perfectly with the user friendly field name that users see.

One instance where someone might need to know the internal name is when dealing with the client-side rendering (CSR) functionality introduced in the 2013 platform. Overriding specific columns requires the internal name.

Finding the internal name thankfully is pretty straightforward. You can find it by going to the List Settings and clicking on the column name you are looking for. The URL will show the internal name at the end of the string:

https://tsdemo13.sharepoint.com/sites/d1/_layouts/15/FldEdit.aspx?List=%7B81E61C92%2DED5A%2D4BE3%2DBA09%2D821C0343DC23%7D&Field=MoreText

In this example, the internal name of the field is ‘MoreText’. You can see it there at the end as part of the ‘Field=MoreText’.

Kudos to Raymond for figuring this out while we were digging into CSR… Smile