Flexible Datatables <img src=“https://badge.fury.io/rb/flexible_datatables.svg” alt=“Gem Version” />

Easily integrate JQuery Datatables (with Ajax) into your Ruby / Rails web applications.

Introduction

Flexible Datatables wraps array-like objects (ActiveRecord::Relation collections, etc) that JQuery Datatables can read (via ajax) from your Ruby / Rails web application.

Features

Any arbitrary array-like collection of data, from plain old ruby arrays to complicated ActiveRecord (or Arel, or plain SQL) query results, can be passed on to JQuery Datatables with very little configuration overhead.
Server-side pagination with Kaminari can be used, out of the box.

Background

This library was inspired by Ryan Bates’ excellent Railscast episode and the ajax-datatables-rails gem.

So why not just use ajax-datatables-rails?

I wanted to be free to use (abuse) SQL to generate the result set to be passed to DataTables. The ajax-datatables-rails library constructs ActiveRecord queries on the application’s behalf, based on user-supplied column names.
I also wanted to the ability to sort on any kind of column, from integer column types to non-string / non-text based columns, to aggregate functions, and so on.
Although I usually choose PostgreSQL as my Rails DB backend of choice, I wanted to be able to pass in any kind of array-like collection (or even use a different database backend altogether).

Installation

First, make sure you have DataTables installed. You have a few choices here. If you are integrating DataTables with a Rails project, the easiest route is via the jquery-datatables-rails gem. Be sure to follow the installation instructions if you choose this route. You can also use bower, or you can even leverage DataTables’ cdn.
Add this line to your application’s Gemfile:
```
gem 'flexible_datatables'
```
And then execute:
```
$ bundle
```
Or install it yourself as:
```
$ gem install flexible_datatables
```

(optional) Create the file config/initializers/flexible_datatables.rb. You can use this to override default values (such as the choice of pagination).

FlexibleDatatables.configuration do |settings|
  # settings.paginator = FlexibleDatatables::KaminariPaginator
  settings.paginator = FlexibleDatatables::SimplePaginator
  # settings.items_per_page = 10
end

Usage

Rails

NOTE

Flexible Datatables isn’t required if you wish to use DataTables to transform an html table without using ajax (see the first part of the DataTables RailsCast for reference).

The benefit of using Flexible Datatables comes when one wishes to have DataTables tables displaying data from a Rails backend using ajax.

Controller

Flexible Datatables requires the draw, start, length, and order keys from the params hash. Initialize a new FlexibleDatatables::Datatable object and pass in those values.
```
datatable = FlexibleDatatables::Datatable.new(params.slice(:draw, :start, :length, :order))
```
Pass in a collection of objects (which can come from anywhere; an array, an ActiveRecord query, etc)
```
datatable.collection = MyModel.all
```

Tell your Datatable object what your columns are and how to arrange them into rows.

datatable.format_grid(%w(first_column, second_column, third_column) do |record|
  [record.first_column, record.second_column, record.third_column]
end

Instruct Rails to render your Datatable object as JSON. Your controller may look something like this:

respond_to do |format|
  format.html
  format.json do
    datatable = FlexibleDatatables::Datatable.new(params.slice(:draw, :start, :length, :order))
    datatable.collection = MyModel.all
    datatable.format_grid(%w(first_column, second_column, third_column) do |record|
      [record.first_column, record.second_column, record.third_column]
    end
    render json: datatable
  end
end

View

Define a table with an id attribute.
Give the table a data-source attribute that points to the route that DataTables will use to get the json data over ajax.
Give this table a thead with some header columns, and an empty tbody declaration.

JavaScript

Finally, in a javascript file, call .DataTable() and pass in values for the processing, serverSide, ajax, and pagingType parameters.

$ ->
  $('#my_table_id').DataTable
    processing: true
    serverSide: true
    ajax: $('#my_table_id').data('source')
    pagingType: "full_numbers"

Contributing

Fork it
Create your feature branch (git checkout -b my-new-feature)
Commit your changes (git commit -am 'Added some feature')
Push to the branch (git push origin my-new-feature)
Create new Pull Request

License

GPL-3.0+