JSLink and DataTables

jsdatatables

Whenever I have to work with client side tabular data, I like to pull in DataTables since it is such a powerful plugin. For those of you who are not familiar with DataTables check the link or the info at the end of the post.

SharePoint itself of course has its default way of presenting tabular data, mainly through the well-known OOTB List View:

1

This default view has some nice options, like paging and search but lacks in UI goodness and some advanced options like multi column ordering. So how would we go from this OOTB view to a much nicer DataTables view like this one?

2

Before SharePoint 2013 we had to use SharePoint Designer, custom XSLT List Views or even entire custom Web Parts to achieve the aforementioned DataTables view. SharePoint 2013 adds the ability to leverage Client Side Rendering and it is a totally new concept. It allows you to render your own output for list views, fields and forms. The rendering is based on HTML, CSS and Javascript and can be deployed using simple files.

In this post, I will create a custom List View and present the list data using DataTables. What do we need?

  • Since DataTables is a jQuery plugin, you need it loaded on the page where the view is used. You can use a Content Editor Web Part, custom masterpage or CustomAction to reference the file from a document library or CDN. I prefer the CustomAction, but any option should work.
  • DataTables library. The actual library containing the plugin.
  • Optionally a theme integration JavaScript file. In this example I used the jQuery UI plugin, but you can also style the DataTable yourself with or without the use of a HTML framework like Foundation or Bootstrap.
  • Optionally a DataTables CSS file if you want to control the table style.
CSS jquery-ui.dataTables.min.css DataTables CSS with jQuery UI theme
Images <several> Images used by the jQuery UI theme
JS jquery.dataTables.min.js DataTables library
dataTables.jqueryui.min.js jQuery UI integration file

Once the files are available and loaded on the page, we need to create our JSLink file. Please note that JSLink inner workings is beyond the scope of this article. Fortunately, there is quite a lot of information available on the web. See this link for more information: http://msdn.microsoft.com/en-us/magazine/dn745867.aspx

The Solution

We need our solution to be a bit generic, because we do not want to hardcode column names and column types. So in this case, our default view supplies several columns and we have to take care of the correct rendering.

We need the following code to setup (“register”) our DataTables Template and take handle the dynamic column names:

function registerDataTables() {
	var itemCtx = {};

	itemCtx.Templates = {};
	itemCtx.Templates.Header = &amp;quot;&amp;lt;table class='display' id='datatablesListView'&amp;gt;&amp;quot;;
	itemCtx.Templates.Item = ItemOverrideDataTables;
	itemCtx.Templates.Footer = &amp;quot;&amp;lt;/table&amp;gt;&amp;quot;;
	itemCtx.ListTemplateType = 100;
	itemCtx.OnPostRender = [];

	itemCtx.OnPostRender.push(function()
	{
		var columns = [];
		var index, len;
		for (index = 0, len = ctx.ListSchema.Field.length; index &amp;lt; len; ++index) {
			columns.push( {&amp;quot;title&amp;quot;: ctx.ListSchema.Field[index].DisplayName });
		}

		$(&amp;quot;#datatablesListView&amp;quot;).dataTable(
		{
			&amp;quot;columns&amp;quot;: columns
		});
	});

	SPClientTemplates.TemplateManager.RegisterTemplateOverrides(itemCtx);
}

This code sets up the DataTables container (the HTML table structure) and the list item override. On Post-Render it scans the available column names (from ctx.ListSchema.Field) and initializes the dataTable plugin.
For the list item override we have the following code:

function ItemOverrideDataTables(ctx) {
	var rowItem = &amp;quot;&amp;lt;tr&amp;gt;&amp;quot;;

	var index, len;
	for (index = 0, len = ctx.ListSchema.Field.length; index &amp;lt; len; ++index) {
		var cell = &amp;quot;&amp;quot;;

		//Test for Array
		if (Object.prototype.toString.call(ctx.CurrentItem[ctx.ListSchema.Field[index].RealFieldName]) === '[object Array]' ) {
			for (index1 = 0, len1 = ctx.CurrentItem[ctx.ListSchema.Field[index].RealFieldName].length; index1 &amp;lt; len1; ++index1) {
				cell += ctx.CurrentItem[ctx.ListSchema.Field[index].RealFieldName][index1].title + &amp;quot; &amp;quot;;
			}
		}
		else if (ctx.ListSchema.Field[index].Name === &amp;quot;LinkTitle&amp;quot;) {
			cell = &amp;quot;&amp;lt;a href='&amp;quot; + ctx.displayFormUrl + &amp;quot;&amp;amp;ID=&amp;quot; + ctx.CurrentItem.ID +  &amp;quot;'&amp;gt;&amp;quot;;
			cell += ctx.CurrentItem[ctx.ListSchema.Field[index].RealFieldName];
			cell += &amp;quot;&amp;lt;/a&amp;gt;&amp;quot;;
		}
		else {
			cell = ctx.CurrentItem[ctx.ListSchema.Field[index].RealFieldName];
		}

		rowItem += &amp;quot;&amp;lt;td&amp;gt;&amp;quot; + cell + &amp;quot;&amp;lt;/td&amp;gt;&amp;quot; ;
	}

	rowItem += &amp;quot;&amp;lt;/tr&amp;gt;&amp;quot;;

	return rowItem;
}

This function is responsible for constructing the table rows and individual cells. In my example I take care of a couple of specific field renderings:

  • Arrays, to handle most of the SharePoint multi-select field types
  • LinkTitle, to render a link to the item (from the displayFormUrl property)
  • Generic fields that just need to display a text value

You will have to adjust this if you want the template to behave differently. We save this code to a separate JSLink JavaScript file so we can reference it from our Web Part properties.

The Setup

The setup of the solution is quite easy since you just need to copy the files to a shared location (for instance the Style Library, Asset Library or Master Page gallery. The most important part is to have the JavaScript and CSS files loaded on the page you enable this view on. As mentioned earlier, there are multiple ways to achieve this so you should be able to get this to work. Just remember, you only need the support files pre-loaded on the page and not the actual JSLink file. That file we can reference from our Web Part properties:

3

Once saved and published, the page should show the new and shiny data view. Oh, and dataTables has a ton of options so make sure you check out the links below if you are interested.

Download the sample files here: Blog.Examples.DataTables.zip

More info on Datatables:

DataTables is a plug-in for the jQuery Javascript library. It is a highly flexible tool, based upon the foundations of progressive enhancement, and will add advanced interaction controls to any HTML table.

  • Highly configurable
  • Super-fast
  • Pagination, instant search and multi-column ordering
  • Supports almost any data source: DOM, Javascript, Ajax and server-side processing
  • Easily theme-able: DataTables, jQuery UI, Bootstrap, Foundation
  • Wide variety of extensions
  • Extensive options and a beautiful, expressive API
  • Fully internationalisable
  • Professional quality
  • Free open source software

https://datatables.net/

Advertisements

10 comments

  • Hello Yuri,

    I have followed the above tutorial and I am able to attach the JavaScript file using JSLink and add the other CSS and JS files using content editor. But my listview does not show dataTables tabular presentation.
    One thing that is not clear to me is how to reference the list that we are trying to render using dataTables and also should we have in the web part an element with the ID of display’ id=’datatablesListView’. It is not very clear from the listed steps.

    Thanks for your help.

  • Yuri,

    It worked perfect by following above steps.

    Thanks for helping.

    I have a blog post request when possible. The request to have a blog entry on how to group rows using this same JSLink approach and dataTables.

  • I”m wondering if multiple DataTables on one Page is possible using this approach? The first DataTable renders but the 2nd one doesn’t. thanks!

  • Very useful article Yuri. Is the example files (Blog.Examples.DataTables.zip) still available? The link is not working for me. Thank you.

  • Nevermind about the download link, I got it to work by adjusting some IE settings. Thank you again. BB

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s