Sunday 20 January 2013

Using JSLink to change the UI of a SharePoint list/view

Changing the user interface of certain bits of SharePoint has always been somewhat challenging – at least, if we want to avoid the SharePoint Designer route and produce something which is packaged, deployable as a WSP and repeatable across many sites. Not to mention source-controlled. A common area of customization is the user interface around SharePoint lists - when it comes to this, there are a few “flavours” of common requests:

  • Custom list forms – e.g. a more “designed” form for adding and/or editing items
  • Custom behaviour for a certain field - e.g. a “UK address” field which allows postcode lookup
  • Custom rendering of a list in display mode (e.g. the ‘All items’ view) – a good example of this is conditional formatting e.g. “Add a red background to the row if the value for ‘Days overdue’ is over 5”

As you might guess from the article title, it’s the third scenario that this article focuses on, for SharePoint 2013 specifically.

Earlier versions of SharePoint gave us a couple of approaches for fulfilling some of these requirements. We could create a custom field control (item number 2 above) or modify the XSLT of an XsltListView perhaps (number 3 above) – a method that was new in SP2010 of course, since we previously had CAML rendering for list views (yuck). SharePoint 2013 brings a new JavaScript-based approach for modifying the UI of fields and lists, and many more things too. You’ll often see this referred to as “JSLink”, because many things in SP2013 have a new JSLink property which you use to point to your JavaScript file. Here’s a list of SharePoint objects which you can modify in this way:

SharePointTypesWithJSLinkProperty

Lots of interesting possibilities there – all the field types are obviously represented, but binding UI changes to a:

  • content type
  • form
  • view
  • list view web part instance (rather than to the list/view itself)

..could all be extremely useful.

[As an aside, if you came to this article looking for a solution to the 1st scenario above (modifying forms), you’ll probably be interested that SPForm has a JSLink property. However I imagine there’s still a place for providing entirely custom forms as opposed to making relatively small changes with JavaScript. The old approaches still apply here - modifying list forms is easy in SPD, but requires a bit more thought in the Visual Studio world. In that case, we’d probably want to NOT edit the original .aspx, but instead provide a different .aspx file and update the SPList.NewFormUrl and/or SPList.EditFormUrl properties to point to it (e.g. in a Feature receiver).]

Implementing changes to list rendering with JSLink

For a recent SharePoint talk, I wanted a fairly dramatic example of changing the UI of a list (when looking at list items). So, my example showed changing the list from this:

JSLink_NoCustomTemplate

..to this:

JSLink_AccordionList1

There are some slightly nasty scrollbars in these images, but that’s just because I’ve reduced the size of the window for my screenshots - normally the accordion looks great. As you might imagine, I get a nice sliding “expand and contract” experience when I select different items:

JSLink_AccordionList2

If you’ve worked with it before, you’ll immediately recognise this as the accordion from jQuery UI. In many ways, it’s a nice example, since although YOU are unlikely to need/want to use jQuery accordion for your “customizing a list” needs, it uses custom CSS, images and JavaScript to provide rendering which you probably ARE going to need. So, I’ll walk through most aspects of this process, but as you’ll see only around 20% of the work relates to the JSLink stuff – the rest is just scaffolding. We’ll cover the JSLink specifics first.

The full Visual Studio project can be downloaded at the end of this article.

The important bit (part 1)– how to hook up your custom rendering with JSLink (e.g. call into jQuery UI accordion)

The first thing to say is that when we want to change the rendering of a SharePoint list, it’s actually individual views (SPView) we’ll be working with. The SPList class does NOT have a JSLink property, which makes sense given this is all about presentation. Getting SharePoint to “see” your custom rendering will probably depend on what you’re doing:

Scenario

Approach

Creating a new list Specify the path to your .js file in the schema.xml file for the list (specifically within the declaration for the view)
Modifying an existing list In code, update the SPLink property (i.e. SPView.JSLink) to provide the path to your .js file (using PowerShell/server-side/client-side API as appropriate)

This bit only ensures your .js file is referenced by the page. You also need to make sure it has the right contents to register your display templates – we’ll come to that in a second.

In my case, I’m creating a new list – it’s worth noting that I’m assigning a list type ID of “11000” – we’ll use this later with respect to JSLink:

CreateListForAccordion3

When developing for SharePoint 2013 onwards, when a list is created in Visual Studio the JSLink element for any views will contain “clienttemplates.js”:

NewCustomList_DefaultJSLink

..but we should change that to our custom JavaScript file which has our display template implementation (you’ll see me deploy this later):

NewCustomList_CustomJSLink

Our file will then be loaded when this view is requested (i.e. SharePoint will add the .js file to the page). But that’s not enough – we now have to think about what JavaScript is needed to actually register the templates. This is done by specifying two properties of the list views to match:

  • OPTIONAL - the BaseViewID property (e.g. BaseViewID=1 for a standard view like “All items”, but you could use another ID for a custom view)
  • The ListTemplateType property (for a new list, you’ll be specifying a unique integer value e.g. 10000)

So, it’s usually a combination of THREE controls overall which dictate how rendering is applied to a list view – the JSLink path, BaseViewID and ListTemplateType. Although BaseViewID appears to be optional, it seems sensible to set it to avoid unforeseen problems with Explorer View/Datasheet View etc. So for a given list, if you wanted one view to have custom rendering and one to have default rendering (even though they share a BaseViewID), simply ensure the JSLink property for the default one is NOT set to your custom .js file.

I also note that it appears possible to specify multiple values in a JSLink path – I haven’t tried this, but I see things like <JSLink>mquery.js|contentfollowing.js</JSLink> (note the pipe character) within out-of-the-box files under the 15 folder.

The important bit (part 2)– what your JavaScript should look like:

Here’s my full AccordionListView.js file specified in the JSLink property for my view – I supply a header and footer and then a JavaScript method (function pointer) to execute for each list item. Notice some context gets passed to this function, including details of the list item:

As you might be able to infer, the jQuery UI accordion expects a H3 and div element for each item – so that’s what my template does, in addition to actually calling the accordion() method.

An issue with JSLink and the Minimal Download Strategy (MDS)?

Continuing my recent tradition of discovering slightly strange behaviour around what I’m writing about, this week is no exception. In my testing, I noticed that if a list has multiple views and the user switches between them, the client templates specified by JSLink do not get applied if MDS is enabled (even though the debugger shows they are called). I’m hoping that I’m doing something wrong, but I can’t rule out a bug in SharePoint 2013’s MDS framework at this stage.

If anyone sees this/has any info, please leave a comment :)

Integrating CSS/JS (such as jQuery UI) into the solution

OK, so if all you wanted to know about was the JSLink aspect, we’re now done covering that. Hopefully that was useful. The remaining bits of this article will cover the “scaffolding” aspects of my particular jQuery UI accordion example – integrating jQuery/jQuery UI, and so on.

My first step was to go to the jQuery UI Download Builder and download the files (plus jQuery too if you don’t have it already). If you haven’t done this before, you can basically configure some options (e.g. styles, behaviors, jQuery UI widgets to use) to build a package for download – this means you get a smaller package than if you were opted for all styles and all jQuery UI components. You’ll therefore have lower page weight and better performance, than if you were using the full set. However, I had an issue where my solution would only work with the full jQuery UI file rather than the one I “built” – if this was production code I’d stop and resolve this, but for demoware I was OK with it.

When you get your download and crack it open, you’ll have some CSS and JavaScript files:

jQueryUIFiles

jQueryUICSSFiles

jQueryUIJSFiles

I chose a grey-ish theme called “overcast”, and within the CSS folder come a stack of images – we’ll need to integrate all of these files into our VS project:

jQueryUIThemeImages

In my project, I created a “Site Assets” folder to house my supporting images, CSS and JavaScript – since I’m working in a sandboxed solution, I need these to go into the content database and in my case the contents get deployed to the SharePoint library of the same name. After copy/pasting these files into my Visual Studio project, I get this:

jQueryUI_FilesInSolution

..and, 0f course, Visual Studio is kind enough to detect the new files and generates my elements.xml file accordingly:

The next step is to ensure the site we’re deploying to references these files – we’ll deal with JavaScript first and then CSS.

Add jQuery/jQuery UI to the page (in this case, every page in the web)

Here we need to ensure jQuery and jQuery UI are added to pages in the site. Since we’re not deploying a custom master page (and don’t want to use the Content Editor web part to add JS to the page), we’ll need to use either CustomAction + ScriptLink or a delegate control going into ‘AdditionalPageHead’. In my case I’m choosing the former so that my solution works in the cloud (as a sandboxed solution):

Notice that I’m referencing a non-minified version of jQuery UI – that was the issue I said earlier that I would resolve for production use. The next step is CSS.

Ensure the jQuery UI branding/CSS is applied

Since we’re not using a custom master page, we’re just using the AlternateCssUrl property of the web to ensure our custom CSS file is referenced by our pages:

Our site should now receive all branding and JavaScript dependencies – so if we were to deploy a static page with the correct HTML for a jQuery UI accordion, then it should work fine. However, we want ours to serve as the UI for a SharePoint list, so we’ll now create that list. In the final step we’ll do the actual JSLink work – this will change the rendering of the list at run-time.

Create the list we will use with JSLink

Nothing special here and I won’t go into every step – but it is worth mentioning that creating a list via Visual Studio 2012 is much easier than before:

CreateListForAccordion

..then add whatever columns your list needs (here I’m adding them direct to the list rather than to a content type):

CreateListForAccordion2

As we mentioned earlier, we are allocating a new list type ID  (the value used was 11000) for the underlying template for this list – this is important since, in this “new list” scenario, we’re using a combination of this and the BaseViewID for the "All items” view to hang our JSLink customizations off:

CreateListForAccordion3

Finally I add some dummy data (some old blog articles) to my list so each time I deploy/test, I don’t have to manually add list items:

Download link

You can download my Visual Studio project for this sample here.

Conclusion

SharePoint 2013 brings some great possibilities for customizing the user interface, and JSLink/client-side rendering is central to much of this. The great news is that it’s all cloud-friendly, so these techniques can be used in Office 365. The solution above was implemented as a sandboxed solution, and the only code was really to set the AlternateCssUrl of the site. As a result, it would be fairly easy to move all this to a SharePoint app if needed.

Hopefully this has been useful in understanding how JSLink/client rendering might be a valuable tool.

Sunday 6 January 2013

Calling SharePoint search using REST (e.g. from JavaScript or an app)

Sidenote - although this article focuses on search, I’ve tried to generalize slightly so that it may also be useful for:

  • Understanding the pattern for working with *any* SharePoint 2013 REST API (e.g. social, querying lists/libraries etc.) – the URL used for the REST call is the main piece that would change
  • Seeing (broadly) how to process REST API results formatted in the two available formats - JSON or XML
  • Understand how to call a REST API from both a SharePoint-hosted app (JavaScript) and a cloud app (provider-hosted or auto-hosted – C#)
  • Briefly discuss using CSOM to call search instead of REST

Often it’s valuable to leverage SharePoint services such as search, user profiles, Managed Metadata and so on from an app. With search specifically, an example I’ve been giving recently is my ‘learner’ time-tracking app, which displays a ‘Related content’ bar with links to documents and other things which relate to completing timesheets:

MainPage3

RelatedContent2

My search query is somewhat simplistic (I’m currently just searching for any documents and pages which contain the term ‘timesheets’), but it’s easy to imagine that with some refinement we could return only highly-relevant items. A nice approach in real-life could be to have a configurable value to allow each client (who installs the app) to edit/store the search query that works best for them. Regardless, I think the main point is that search can be a valuable ‘bridge’ between an app and the rest of the SharePoint environment. In my example, consider that:

  • As the app vendor, I have no idea what your organization’s timesheet policy/guidelines are
  • If I can bring in some of your content around this, users will have more success with my app, and that’s good for everyone

In terms of implementation, I’ll now talk about the basics of accessing search via REST, and also how to do this from an app.

Broadly, the process is:

  1. Identify (and test) the REST URL to use
  2. Deal with app authentication if necessary (i.e. you’re calling from outside SharePoint, e.g. a cloud app)
  3. Add a Permission Request to your app, so that a request to use search is successful
  4. Develop the success handler code to process the results

Accessing search via REST (_api)

The beauty of REST is that it’s just a URL, and you can test/refine it in the browser before writing a single line of code. From SharePoint 2013, such a URL takes the format:

[site]/_api/[name of SP API]/[name of operation]?[parameters]

So in the case of search, a basic query can be executed with the following:

[site]/_api/search/query?querytext='timesheets'

If such a URL is entered into the browser address bar, then you should see an XML response like this – you’ll find some interesting properties, like those I’ve highlighted in the images:

SearchRESTCallResults

SearchRESTCall_HitHighlightedSummary

Common operations

So far we’ve just looked at executing a basic query where the query text is specified. Here are a couple of other common operations you might want to do:

Operation

Sample REST URL

Use a search Result Source (i.e. a scope) /_api/search/query?querytext='search term'&sourceid='B09A7990-05EA-4AF9-81EF-EDFAB16C4E31' (this example is to search the ‘People’ result source)
Specify a start row (i.e. in paging) /_api/search/query?querytext='search term'&startrow=11
Specify a number of results to return /_api/search/query?querytext='search term'&startrow=11&rowlimit=10 (but note 10 is the default)
Specify particular (managed) properties to return /_api/search/query?querytext='search term'&selectproperties='Author,Path,Title,Url'

For a more comprehensive reference, the best source I can find is the SharePoint 2013 Search REST API post in the ‘Search Space’ blog by ‘nadeemis’ on MSDN – kudos to the author.

Working with the data

As with other SharePoint REST operations, you can choose to have the data in XML or JSON – and JSON might be preferable if you are in JavaScript. As I’ve mentioned before, this is accomplished with the “Accept” header – specify one of the following:

  • headers: { "Accept": "application/json; odata=verbose" }
  • headers: { "Accept": "application/xml" }

Your code which processes the results will need to deal with JSON/XML as appropriate. In either case, you’ll usually have some drilling down to do to get the valuable data – for example, the main result rows are in a property called jsonObject.d.query.PrimaryQueryResult.RelevantResults.Table.Rows.results (where jsonObject is the object which was parsed from the JSON string). And when you’re iterating through the results, if you want the URL for the item, then you can get that from the cell at index 6 with result.Cells.results[6].Value. The title is at index 3, so result.Cells.results[3].Value. These are basically just the things you work out with a JavaScript debugger, or from a code sample like mine below.

Calling the search REST service from the JavaScript Object Model (JSOM)

In this sample, I have a web page which has a DIV waiting to output the search results:

<div id="related-content-results"></div>

If I’m in a page running on SharePoint (including a SharePoint-hosted app), I can use SP.RequestExecutor (as opposed to a jQuery.get() or jQuery.getJson() for instance) and this simplifies things by meaning I don’t have to worry about adding an OAuth header to my request. So, this code would look like:

** N.B. My newer code samples do not show in RSS Readers - click here for full article **

Notice a couple of things:

  • The URL we’re using is the app web, rather than needing to reference the host web somehow – this is fine for search (but isn’t for accessing data in the host web, for example)
  • We need something to iterate over the result items within the JSON – jQuery’s each() operator is a good choice here
  • There are some ‘magic numbers’ in processing the JSON results to get to the values e.g. result.Cells.results[6] to get to the URL of the item. That’s just a reflection of the data structure SharePoint returns, and you’ll see the same if you’re working with XML instead

Calling the search REST service from a cloud app (provider-hosted/auto-hosted) in .NET CSOM

Accessing the search REST API (just like any SP2013 REST API) in other contexts can be a bit more involved. The main consideration is that if your page isn’t on the SharePoint server, you’ll need to deal with OAuth and adding the ‘Authorization’ token to the REST request. If you’re in C# (i.e. the .NET CSOM), then the TokenHelper class automatically added to your Visual Studio project simplifies this – you’ll need to use a HttpWebRequest object (or similar) to call the REST URL, and then process the response. Since I’m on the server this time and have access to .NET, XML could be a better choice here:

And just for clarity, here’s my ASPX page which renders this – as you can see, I’m using an ASP.NET ListView control to put the results on the page:

Sidenote: Other contexts – calling SP2013 REST APIs using jQuery in a cloud app

As I worked through these samples, I realized that another useful approach would be calling the REST API client-side from a cloud app (in an AJAX way). In this case, we’d probably be coding in jQuery, and would need to deal with obtaining an OAuth token and adding it to the web request – but in this case, we don’t have TokenHelper to support us. Sure, you could perhaps wrap TokenHelper in a WCF service and call that from jQuery, but that would mean an inefficient process of multiple web requests (firstly to the service, then the exchange to get the OAuth token, and finally the call to the SharePoint REST API).

Far better would be to eliminate the extra call and just directly obtain the OAuth token and call the REST URL directly from jQuery – but some work is needed to facilitate this. I’m sure someone will look at this soon as I expect it to be a common pattern for SharePoint 2013 app development.

Using CSOM instead of REST

I actually can’t think of too many reasons to do this any more, but if CSOM is your client-side preference you’ll want Microsoft.SharePoint.Client.Search.Query.SearchExecutor.ExecuteQuery(). 

Permission Request for an app to use search

In order to be able to call the search REST API from an app (of any hosting type), the app needs to be granted permission to use the search service – this doesn’t happen by default. Like any permission which relates to “core SharePoint” rather than the app itself, the developer must specify the requirement in the form of a Permission Request, and the administrator installing the app must agree to granting this permission at install time.

So, the developer needs to add the following to the appmanifest.xml file:

Note that the value specified for the Right attribute gives a very descriptive string reminding you what’s being asked for – although most actions within an app run “as the app’s identity” (i.e. as the ‘app principal’), the search will instead be performed as the user (with the associated security-trimming).

In the Visual Studio designer for the appmanifest.xml file, this looks like this:

SearchPermRequest

And, of course, when someone is installing (or upgrading) the app, they’ll see search listed as one of the permissions that the app requires – and can make an informed decision on whether they are OK with this:

Grant_SearchPermRequest

An issue for on-premises deployments?

So everything above works great for Office 365 environments. However, I see something weird when I deploy an app which uses search to my local developer environment. I haven’t yet tested the app against another on-premises environment, but I’d be interested to hear if anyone else sees this – the app in fact cannot be added, and I see a message saying “Sorry, only tenant administrators can add or give access to this app”:

OnPremisesError_AppWithSearchPermRequest

This is curious to me for a couple of reasons:

So, does anyone else see this? Am I missing something? Please let me know in the comments.

Finally, it’s worth pausing to consider – that fetching content via search across an entire SharePoint environment is a fairly elevated level of permission. The app is basically being given access to content created within your business, and anything in the search index is available. Clearly an app could potentially do some ‘interesting’ things with this, so it might be prudent to do some evaluation of such apps before blindly installing.

Conclusion

Calling into search from an app can be valuable, and here we’ve looked at how to do it from both a SharePoint-hosted app (in JavaScript) and a cloud app (in C#). The template used here for making such REST calls can be applied to many other operations – ultimately the pattern is to identify the URL, deal with authentication if outside SharePoint, ensure a permission request exists, then drill down in the JSON/XML response to get to the valuable data.