Datatables

Datatables is a Rails 3 plugin that enables the easy creation of dynamic datatable views on top of any ActiveRecord model. Datatables provides a simple helper that can be utilized in the view to automatically display a dynamic view on top of a model. Datatables handles the entire front end and backend support to do this.

Installation

To install datatables to your rails project, follow these simple steps:

1. Make sure your project is using the ‘jquery-rails’ plugin.

2. Add the following line to your Gemfile:

gem 'datatables', :git => 'git://github.com/Caseproof/datatables.git'

3. Run bundle install

4. Run rails generate datatables:install

5. Add the following lines to your layout file after javascript_include_tag :defaults

<%= stylesheet_link_tag "datatable_page" %>
<%= stylesheet_link_tag "datatable_table" %>
<%= javascript_include_tag 'jquery.dataTables.min' %>

6. Add the Datatable helper mixin to your ApplicationHelper (app/helpers/application_helper.rb) like so:

module ApplicationHelper
  include Datatables::Helpers
end

Example

With datatables it’s easy to add rich datatables to your views that correspond with your active record models.

There is a lovely helper that you can use to render your datatable that takes in a whole host of options. Unfortunately, there’s still quite a bit of work to do with these options to handle every scenario but here’s what it support so far:

Database table:

The following examples will use the following database table:

mysql> desc companies;
+-------------+--------------+------+-----+---------+----------------+
| Field       | Type         | Null | Key | Default | Extra          |
+-------------+--------------+------+-----+---------+----------------+
| id          | int(11)      | NO   | PRI | NULL    | auto_increment |
| name        | varchar(255) | YES  | MUL | NULL    |                |
| slug        | varchar(255) | YES  | MUL | NULL    |                |
| domain      | varchar(255) | YES  | MUL | NULL    |                |
| category_id | int(11)      | NO   | MUL | NULL    |                |
| created_at  | datetime     | YES  |     | NULL    |                |
| updated_at  | datetime     | YES  |     | NULL    |                |
+-------------+--------------+------+-----+---------+----------------+

Standard datatable

The first argument to the datatable helper is the name of the model or an array of model & scope. The second argument is a hash of column names & options.

<%= datatable('company', { :name => { :type => 'string', 
                                      :label => 'Name',
                                      :width => '20%' },
                           :slug => { :type => 'string',
                                      :label => 'Slug',
                                      :width => '15%' },
                           :domain => { :type => 'string',
                                        :label => 'Domain',
                                        :width => '15%' }
                         }) %>

Datatable with a link to edit

Note that the edit link path utilizes the :id field in the database table to automatically insert the correct id on a row by row basis:

<%= datatable('company', { :id => { :type => 'hidden' },
                           :name => { :type => 'link', 
                                          :label => 'Name', 
                                          :link => edit_admin_company_path(:id),
                                          :replace => 'id',
                                          :width => '50%' },
                           :slug => { :type => 'string',
                                      :label => 'Slug',
                                      :width => '25%' },
                           :domain => { :type => 'string',
                                        :label => 'Domain',
                                        :width => '25%' }
                         }) %>

Scoped datatable (now we’re using the ‘dot_org_domains’ that can be found in the Company model):

<%= datatable(['company','dot_org_domains'], { :id => { :type => 'hidden' },
                                               :name => { :type => 'link', 
                                                              :label => 'Name', 
                                                              :link => edit_admin_company_path(:id),
                                                              :replace => 'id',
                                                              :width => '50%' },
                                               :slug => { :type => 'string',
                                                          :label => 'Slug',
                                                          :width => '25%' },
                                               :domain => { :type => 'string',
                                                            :label => 'Domain',
                                                            :width => '25%' }
                                             }) %>

Association columns

<%= datatable(['company','dot_org_domains'], { :id => { :type => 'hidden' },
                                               :name => { :type => 'link', 
                                                              :label => 'Name', 
                                                              :link => edit_admin_company_path(:id),
                                                              :replace => 'id',
                                                              :width => '40%' },
                                               :slug => { :type => 'string',
                                                          :label => 'Slug',
                                                          :width => '20%' },
                                               :domain => { :type => 'string',
                                                            :label => 'Domain',
                                                            :width => '20%' },
                                               :category_name => { :type => 'string',
                                                                   :label => 'Category',
                                                                   :column => 'categories.name',
                                                                   :width => '20%',
                                                                   :class => 'center' }

                                             }) %>

Why use this plugin?

It is the easiest way to integrate dynamic datatables using the jQuery datatables plugin into your rails app.

Version history

Version 1.0.0
- First Release

Contribute

If you’ve got some ideas for datatables let me know and, even better, if you’ve made some enhancements to the code send me a pull request!

Support

Bug report? Faulty/incomplete documentation? Feature request? Please post an issue on ‘github.com/Caseproof/metafy/issues’. If its urgent, please contact me from my website at ‘blairwilliams.com/contact’