DataTables logo DataTables

Sat, 27th Aug 2011

Getting started with DataTables: First steps

DataTables is a powerful Javascript library for adding interaction features to HTML tables, and while simplicity is a core design principle for the project as a whole, it can be quite daunting to get started. In this article I'll introduce the basic concepts that you will need to know to get going with DataTables, and you will find that in a very short space of time you'll be able to create advanced table controls, tuned to your specific requirements.

Dependencies

DataTables has only one dependency (other software upon which it relies in order to work) - jQuery. Being a jQuery plug-in, DataTables makes use of many of the excellent features that jQuery provides, and hooks into the jQuery plug-in system, in the same way that all other jQuery plug-ins work. jQuery 1.3 or newer will work with DataTables, although typically you will want to use the latest version (1.6.2 at the time of writing). DataTables includes everything else that it requires to operate.

HTML requirements

All DataTables needs in your HTML is a <TABLE> which is well formed (i.e. valid HTML), with a header (defined by a <THEAD> HTML tag) and a body (a <TBODY> tag). A typical table might look like this:

<table id="table_id">
	<thead>
		<tr>
			<th>Column 1</th>
			<th>Column 2</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<td>Row 1 Data 1</td>
			<td>Row 1 Data 2</td>
		</tr>
		<tr>
			<td>Row 2 Data 1</td>
			<td>Row 2 Data 2</td>
		</tr>
	</tbody>
</table>

If you are generating your HTML document using a server-side program, such as a PHP script, a Ruby script, a C# program or anything else - all they need to do is output your table like this. This is exactly what you would have for a normal HTML table, although sometimes you might need to add the <THEAD> and <TBODY> tags, as these aren't always used (they allow DataTables to know what should be used for the column headers and the click-to-sort controls).

Including the Javascript and CSS

The first thing to do when you want to use DataTables, is to download the latest version from the DataTables download page. Unzip the downloaded file and upload it to your web-server.

To be able to use DataTables on your page, you must first include the library in your web-page; this is done using the <SCRIPT> tag to load a Javascript file. You must include both jQuery and DataTables - which can be done by adding the following to your HTML document's <HEAD>:

<script type="text/javascript" charset="utf-8" src="/DataTables/media/js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="/DataTables/media/js/jquery.dataTables.js"></script>

You might already have jQuery on your web-page, in which case just drop the first line from above and include DataTables only.

You will likely want to apply some styling to your table to make it look nice in your web-page! DataTables includes a default stylesheet which can be used to apply the default look and feel to the table. You'll almost certainly want to customise the styling to integrate it with the look and feel of your web-site once you've got DataTables running (there is a separate blog post about how you can style your table as you wish).

To include the default CSS for the table you need to add the class name of "display" to your table (this is done so it doesn't interfere with any other tables you might have on your page), which is done quite simply with your table HTML:

<table id="table_id" class="display">

Then to include the CSS also add the following to your HTML document's <HEAD>:

<style type="text/css" title="currentStyle">
	@import "/DataTables/media/css/demo_table.css";
</style>

Initialising DataTables

That's almost it! We've got the HTML table we want to enhance, and we've got all the software and styles we need. All we need to do now is to tell DataTables to actually work its magic on the table. This is done with a few lines of Javascript:

$(document).ready( function () {
	$('#table_id').dataTable();
} );

If you've used jQuery before, you will know that the first line is used to make sure that the HTML document it ready for Javascript to be run on it (i.e. it the page has been fully downloaded from the server). The second line uses a jQuery selector to get a reference to the table in the HTML and then run the DataTables function on it.

That's it! DataTables will adding sorting, filtering, paging and information to your table by default, providing the end user of your web-site with the ability to control the display of the table and find the information that they want from it as quickly as possible.

There is an example of this basic DataTables initialisation available for you to have a look at and explore. This example is also included in the DataTables download package.

DataTables options

Now that you've got DataTables running, you might want to customise some of the features that it provides, such as turning on scrolling, turning off paging or using something other than just HTML as the data source (an Ajax source for example). There are a huge range of options for DataTables which you can use to customise it exactly as you want. In this example, let's look at how to enable vertical-scrolling on the table, and disable paging.

Options are given to DataTables as Javascript object, with the options you want to specify written in. If you don't specify an option, then the default values will be used for each option (which is how DataTables automatically enables filtering, sorting etc).

In this particular case, we want to use the sScrollY and bPaginate options to enable scrolling and turn off paging (so that all records show in the table together - the scrolling will stop the table being too huge!).

The sScrollY parameter takes a CSS measurement value which will be used for the height of the viewport for the table (anything bigger than this will be in the scrolling), and bPaginate is a simple boolean to turn paging on (true - default) or off (false). This is done as follows:

$(document).ready( function () {
	$('#table_id').dataTable( {
  	"sScrollY": "200px",
    "bPaginate": false
	} );
} );

Next steps

With the basics of how to get DataTables going under your belt, you might now want to explore some of the options that is can provide in order to enhance your tables even further. To explore the world of DataTables further your could:

Enjoy using DataTables!