Category Archives: SharePoint Online

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.

Hiding the Title Field – A little stumble…

Plenty of folks talk about variations on a theme here. I’ve hidden the Title field before, no big deal. The order I happen to use this time was a little confusing though.

I have a list where I know I’m using content types. So right after I’ve created the list, before I do anything else I turn on Advanced Settings –> Allow management of content types and then add my content types to the list. Within those content types, I have the Title field hidden. Within the ‘inherited from’ content types, the Title field is hidden. I figure I’m covered. Now when I open the list in datasheet mode and add a new row of information I get an error. First it was that a required field was not in the view so I needed to add a handful of columns back in. Then, I attempted again to add an item and the Title field gets the red box. What the heck? It’s supposed to be hidden. I tried changing lots of different settings all over the place but nothing worked. Frustrating.

Maybe you’ve seen this, maybe you haven’t – but it stumped me for a while before figuring out the simple solution thanks to Marc Anderson’s post. All I needed to do at this point was turn off the List Settings –> Advanced Settings –> Allow management of content types, then make the Title field not required, then turn Advanced mode back on. Even though I’d done the same thing to all the content types (including Item), I still needed to explicitly change the setting on the field itself. Makes sense once you figure it out, but quite frustrating when you’re in the mix trying to make it work.

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 = “” + ctx.CurrentItem.Status + “”;
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.

SPC14 MySPC, Sessions and Schedule

SPC14 is going to be pretty darn cool. Looking at the sessions and how things are going to be organized is amazing. Microsoft is doing a great job integrating Yammer into the mix for this conference.

If you haven’t already, sign in to MySPC and then link your Yammer account to MySPC. Once you’ve gotten into the SPC 2014 network in Yammer, you’ll be able to search by session numbers to find session presentation information, slide decks, related links and files, etc. The Yammer network integration and ‘second screen’ experience is going to change how you experience the conference – before, during and after the event.

Be sure to check out the sessions you’re interested in on the Yammer network to properly set expectations for what you’re going to see during the presentations.

Here’s information about my session:
#SPC318 – Client-Side Rendering (CSR) demystified
MySPC Link | Yammer Link

It is a developer session and I will be talking about JavaScript code that applies to the web interface, specifically list views but also touching on forms. From a practical viewpoint the content I’ll be covering can be used by what I would call power users, citizen developers, etc. –> folks comfortable tweaking HTML, CSS and a little JavaScript given some guidance.

There’s more information available on the Yammer page. Log on, ask questions, participate in the conversation and I’ll see you on Tuesday!

JS Link – CSR Simple View Field Formatting

One function that SharePoint Designer (pre-2013) was great for was doing some quick formatting changes to views – tweaks not available through normal view configuration. This example shows how you can implement simple changes to the field formatting using SharePoint 2013’s new JS Link property and Client-Side Rendering (CSR) – though some simple JavaScript.

Looking at an Issues app (list), we’ve got a ‘Issue Status’ field that we’d like to show as bold. Here’s how it looks in it’s native default view:

In order to override how a field is displayed (or ‘rendered’ – the ‘R’ in ‘CSR’) you need to create a JavaScript file that defines the Field Override we’re using. The full contents are shown here:

Much of this code is boilerplate. The key line in this is:
’Status’:{‘View’: ‘<#=ctx.CurrentItem.Status#>’}

and it breaks down like this:

’Status’:{‘View’: ‘<#=ctx.CurrentItem.Status#>’}
’Status’ is the column in the view being overridden.
’Status’:{‘View’: ‘<#=ctx.CurrentItem.Status#>’}
’View’ is the type of page
’Status’:{‘View’: ‘<#=ctx.CurrentItem.Status#>’}
This is the HTML string that is constructed to replace the current contents of the column. The ctx.CurrentItem.[InternalFieldName] is referring to the column value of the item. This is where things can get as complicated as you want to make them by building more complex strings, combining field values much like a calculated field but using JavaScript instead of the Calculated Field type.

As mentioned in my other posts, you need to use the internal field name when referencing it in the code. You can find this in a number of ways but the easiest for me is to look at the list settings and click on the field name you’re looking at. The URL will show the internal name in the string (example shown below). With this particular example we can see in the Columns listing that the field is referred to as ‘Issue Status’, but that the internal name is actually ‘Status’.

https://yourdomain.com/sites/CSR/_layouts/15/FldEdit.aspx?List…&Field=Status

Upload the JavaScript file to the Master Page Gallery (yes, you can use alternate locations…).

For this example, I created a page in my Site Pages app (library) and added an App Part to the page for the ‘Office Issues’ app that I had created. I left the web part using the default view (shown above).

Note: Technically, you can edit the web part on the actual view page, but I don’t generally like to do that unless there is a really good use-case for it. It can be confusing to users and administrators.

On the page that was created, edit the page and edit the web part. At the far bottom of the web part properties is the JS Link property. Put your file name in the field and click ‘OK’.

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

As soon as you hit ‘OK’, if all the parts are connected your override should be in place and the view should change to reflect your change.

Notes to remember:

You aren’t changing the view itself. If you go to the list and look at the view, it will not reflect your CSR. Only the page where you are applying the CSR will show your changes.
If you want to override more than one field, the code looks like the following:

If you’d like to walk through a simple ‘Hello World’ example to make sure your file is in the right place and your JS Link property is properly set take a look at the following posts:

JS Link – Hello World

JS Link and CSR (Client-Side Rendering) for SharePoint 2013 are often used interchangeably, but they aren’t exactly. The JS Link web part property is a way to add CSR template overrides to your page.

This quick post walks through a ‘Hello World’ scenario that doesn’t do any CSR, but makes sure your JavaScript file is working and that the JS Link reference can find it.

I’ve got a longer post on more of the details and use of JS Link for CSR in SharePoint 2013, but this is a quick ‘Hello World’ version for JS Link. There are three main components:

Create a JavaScript file
This file, saved as [yourFileName.js] literally only needs to have a single line:
alert(“Hello World”);
Put the file in a location where your JS Link reference can see it.
- One common location to upload to is the Master Page Gallery though other locations can be used. This does require higher permissions on the site, however.
- Using this ‘Hello World’ approach is a great way to test the location of your file, the permissions to that file and the JS Link string (next step) used to get everything working.
- If you are a site collection administrator you can use SharePoint Designer 2013 to view ‘All Files’ in the Master Page Gallery and add a new JavaScript file that way.
Point your web part to the JavaScript file.
You are changing the properties of a web part here. Technically you can edit the web part of a standard view for a list, but I generally don’t do that.
1. For this example create a page on the site and drop a web part from your test app (list or library) on to that page.
2. Edit the page and Edit Web Part. At the far bottom of the web part properties, under the Miscellaneous grouping is the ‘JS Link’ property.
3. Enter the following and click OK.
  ~site/_catalogs/masterpage/[yourFileName].js
If everything is working as planned, as soon as you click ‘OK’ you should get a JavaScript alert that says ‘Hello World’.

Now, you can start playing with CSR or other functionality with the JS Link. Check out my Primer post… more examples are coming shortly. Smile

SharePoint Fest Chicago

I’ve got two sessions this week at SharePoint Fest Chicago.

PWR104 – Build a SharePoint Intake / Request List

PWR202 – Customizing Sites and Pages in SharePoint 2013

Slide decks for both will be up shortly. I need to make a few tweaks and updates to capture a few missing screenshots that were missing. Thank you for your patience.

SharePoint Saturday Twin Cities–May 2013

Another great event this past weekend – for those of us that were able to navigate the monsoon in the morning. Almost 500 attendees made it in.

Slide decks should be posted to the www.spstc.com soon. Until then I posted mine out on Slideshare if anyone wants to take a peek at them.

SharePoint 101: What is this thing called ‘SharePoint’?
This is a really high level overview of what SharePoint is and what it offers to an organization…

Understanding SharePoint Roles
This is an overview of all the different roles and responsibilities that can play a part in a SharePoint implementation… lots of discussion during the session…