DataTables is a very powerful open source jQuery plugin, that enhances any HTML table to enable filtering, colum sorting, loading data via AJAX, pagination, etc. There are many other plugins for building data tables, but in my opinion this one is especially easy to customize and also very well documented.
In this tutorial we are going to use the official AJAX-example from the DataTables documentation within a jQuery mobile page: see the result in the live demo. In fact, DataTables work very well with jQuery mobile right out of the box, if you initialize the plugin at the right time - that is, when the mobile page is about to be shown. In short, here is the code to create a data table on a jQuery mobile page:
<script language="javascript">
<!--
$(document).on("pageshow", "#dataTablesExample1", function() {
if ($.fn.DataTable.isDataTable( '#example' )) {
$('#example').DataTable().columns.adjust();
return;
}
$('#example').dataTable( {
"scrollX": true,
"scrollXollapse": true,
"ajax": 'assets/files/demos/jquery_mobile/datatables/dt_ajax_example.json',
"pagingType": "full"
} );
} );
$(document).on( "pageremove", function( event ) { $('#example').DataTable().destroy(false); } )
-->
</script>
<div data-role="page" id="dataTablesExample1" data-theme="a">
<div data-role="header">...</div>
<div data-role="content">
<table id="example" class="display" cellspacing="0" width="100%">
<thead>
<tr>
<th>Name</th>
<th>Position</th>
<th>Office</th>
<th>Extn.</th>
<th>Start date</th>
<th>Salary</th>
</tr>
</thead>
</table>
</div><!-- /content -->
<div data-role="footer">...</div>
</div><!-- /page -->
Now, let's take a closer look. The main difference to the non-mobile initialization is that we bind the script to the pageshow event of jQuery mobile. This event is fired right after the page has beed completely loaded, all transitions are finished and the user sees the final result. At that point, the DOM is completely rendered and it is safe to enhance our table.
Note, that the table is responsive and takes up the entire width of the page. It also reacts to changing screen orientation. On smaller sreens the columns will narrow as far as possible. After a certain point (depending on the width of the displayed data) the table will get a horizontal scroll bar, so the user can swipe to see the columns, that did not fit on the screen. You can also use the responsive extension for DataTables, if you prefer stacking columns on small screens.
If you use jQuery mobile in AJAX mode (that's the default), pages that are currently not visible to the user, may get removed from the DOM to save memory. That is why every time the page is shown, we need to check first, whether the DataTable is already initialized using $.fn.DataTable.isDataTable(). If the user navigates to another page and returns back to the one with the table, the whole table markup might still be there in the DOM or may have been removed already. In the former case, we just need to recalculate the column widhts, while the latter requires a complete reinitialization.
Since the page containing the data table can be removed at any time in the background, it is also a good idea to make sure, there is nothing left of our table, once the page is removed. To achieve this, we bind DataTable().destroy(false) to the pageremove event of jQuery mobile. Passing the argument false makes sure, the initial state of the table (before enhancement) is restored. This way, even if something goes wrong and the page is not removed after all, the data table will get enhanced again the next time the page is shown.
In theory, you can also initialize the table in the background using the pagebeforeshow event, but you will still need to adjust it's width to the final page dimensions by binding DataTable().columns.adjust() to pageshow. Enhancing the data table before the user gets to see it might make the transition to the page with the table smoother, but I have not noticed too much difference. Feel free to experiment though!
