jQuery DataTables

jQuery DataTables is a great jQuery plugin for enhancing HTML tables. It is not only packed with features, but is also really well documented, and free to use under the MIT license. Data tables are a ubiquitous requirement in any admin console, and so are worth including out of the box.

We've not only provided the plugin as a standard feature, but also integrated it tightly with Angular as well as with Rails, to enable quick, declarative implementation of paging, sorting and filtering through any data in the database.

Features We Provide

• datatable Angular directive for creating a responsive data table on screen
• DataTableAdapter Ruby class for doing the grunt work of parsing data table requests, assembling the results and formatting them for consumption by the data table. All you need to add is 1 line of code.
• Multi-row selection and custom bulk operations (these are not a part of vanilla jQuery Datatables)
• Custom single row operations
• The ability to render Angular directives within data table cells
• Advanced multi-condition data filtering when combined with the query-builder directive - itself a highly flexible utility
• The ability to expand rows to show additional information

Screenshot

Setup and Usage

Lets say you want to display a data table of users. You'll need:

• An Angular view to display the table (with paging, filtering & sorting)
• An Angular controller powering the view
• A Rails controller to handle page/filter/sort requests from the data table
• A Rails view to render the Rails controller result into data table friendly JSON
• A Rails User model

We'll tackle the Angular code first, and then the Rails code, by showing exactly such a setup already built into this starter kit.

The Angular View

• Displays the data table
• Located at /app/assets/javascripts/templates/admin/controllers/users/index.html.

It declares a table element that is powered by the datatable directive. Various attributes on the element set up functionality such as multi-row selection and bulk operations.

Data tables by default work on all screen sizes, by the simple process of horizontal scaling. However, if you need slightly smarter responsive behaviour, add the 'responsive' class to the table element. We generally don't see any real benefit by doing this, but the feature exists if you want to use it.

It also declares a query-builder element that is linked to the data table to provide multi-condition filtering.

The values supplied to the attributes of these elements come from the controller powering this view (see next).

The Angular Controller

• Powers the Angular view
• Located at /app/assets/javascripts/admin/angular/controllers/users_ctrl.js

The values to be passed to the directives above are defined in $scope.actionIndex. The code is well commented, and in conjunction with the documentation for the data-table and query-builder directives, and the jQuery DataTables library (see links above), should be enough to illustrate the following:

• How to wire up a data table
• How to custom render columns in a data table
• How to wire up a query builder, and link it to the data table
• How to enable multi-row selection and bulk operations
• How to set up manually set up single row operations (the data-table directive also declaratively supports single row operations, which is discussed below)

For declarative single row operations in action, see the following:

• /app/assets/javascripts/templates/admin/controllers/posts/index.html
• /app/assets/javascripts/admin/angular/controllers/posts_ctrl.js

In particular, look for code containing $scope.dataTableRowOps and row-ops=....

The Rails Controller

• Handles page/filter/sort requests from the data table
• Located at /app/controllers/admin/users_controller.rb

The index action caters to requests from the data table, and makes use of two Ruby classes that do most of the grunt work:

• DataTableAdapter for parsing data table requests and generating final results
• QueryBuilder for parsing the filtering portion of the data table request and generating filtered results, which are then passed on to DataTableAdapter for further processing

Although these two classes handle several use cases out of the box, they can be customized if required. For example:

DataTableAdapter normally fetches only those columns from the database that are requested by the UI (for efficiency), but can be customized on-the-fly to fetch extra columns, or exclude some data table columns that do not map to database columns. See an example in AttachmentsController, in the index action.

QueryBuilder too tries to map UI requested columns to database columns, and supports many operators out of the box. However, it can be customized on-the-fly to handle cases where a UI column does not exist in the database, or the UI provides a custom operator. Look for this snippet (in the users controller itself), and in particular the |filter, query|... block:

    users_filter = QueryBuilder.new(User, params[:filters]) {
        |filter, query| build_custom_logic(filter, query) }

The documentation in the controller code, as well as the two classes above is more than sufficient to illustrate the following:

• How to parse the filtering portion of the data table request and generate filtered results
• How to generate a final result that can be sent back (as appropriate JSON) to the data table
• How to customize DataTableAdapter
• How to augment QueryBuilder with a custom filter when the built-in ones don't suffice

The Rails View

• Renders the Rails controller result into data table friendly JSON
• Located at /app/views/admin/users/index.json.jbuilder

Note the json.DT_RowId user.id line. This is important for jQuery DataTables, to give each row a unique and known id.