ajax-datatables-rails 0.4.0 → 0.4.1

data/.travis.yml

@@ -3,42 +3,52 @@ language: ruby
 sudo: required
 cache: bundler
 rvm:
-  - 2.2.7
-  - 2.3.4
+  - 2.2.10
+  - 2.3.7
 gemfile:
   - gemfiles/rails_4.0.13.gemfile
-  - gemfiles/rails_4.1.15.gemfile
-  - gemfiles/rails_4.2.8.gemfile
-  - gemfiles/rails_5.0.3.gemfile
-  - gemfiles/rails_5.1.1.gemfile
+  - gemfiles/rails_4.1.16.gemfile
+  - gemfiles/rails_4.2.10.gemfile
+  - gemfiles/rails_5.0.7.gemfile
+  - gemfiles/rails_5.1.6.gemfile
+  - gemfiles/rails_5.2.0.gemfile
 matrix:
   include:
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_4.2.8.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_4.2.10.gemfile
       env: DB_ADAPTER=postgresql
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_5.0.3.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.0.7.gemfile
       env: DB_ADAPTER=postgresql
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_5.1.1.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.1.6.gemfile
       env: DB_ADAPTER=postgresql
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_4.2.8.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.2.0.gemfile
+      env: DB_ADAPTER=postgresql
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_4.2.10.gemfile
+      env: DB_ADAPTER=mysql2
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.0.7.gemfile
       env: DB_ADAPTER=mysql2
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_5.0.3.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.1.6.gemfile
       env: DB_ADAPTER=mysql2
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_5.1.1.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.2.0.gemfile
       env: DB_ADAPTER=mysql2
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_4.2.8.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_4.2.10.gemfile
+      env: DB_ADAPTER=oracle_enhanced
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.0.7.gemfile
       env: DB_ADAPTER=oracle_enhanced
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_5.0.3.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.1.6.gemfile
       env: DB_ADAPTER=oracle_enhanced
-    - rvm: 2.4.1
-      gemfile: gemfiles/rails_5.1.1.gemfile
+    - rvm: 2.4.4
+      gemfile: gemfiles/rails_5.2.0.gemfile
       env: DB_ADAPTER=oracle_enhanced
 after_success:
   - bundle exec codeclimate-test-reporter
@@ -53,6 +63,8 @@ addons:
     - mysql-client-core-5.6
     - mysql-client-5.6
 before_install:
+  - gem update --system
+  - gem install bundler
   - sh -c "if [ '$DB_ADAPTER' = 'mysql2' ]; then mysql -e 'create database ajax_datatables_rails;'; fi"
   - sh -c "if [ '$DB_ADAPTER' = 'postgresql' ]; then psql -c 'create database ajax_datatables_rails;' -U postgres; fi"
   - sh -c "if [ '$DB_ADAPTER' = 'oracle_enhanced' ]; then ./spec/install_oracle.sh; fi"

data/Appraisals

@@ -1,33 +1,39 @@
+# frozen_string_literal: true
+
 RAILS_VERSIONS = {
   '4.0.13' => {
     'mysql2' => '~> 0.3.18',
     'activerecord-oracle_enhanced-adapter' => '~> 1.5.0'
   },
-  '4.1.15' => {
+  '4.1.16' => {
     'mysql2' => '~> 0.3.18',
     'activerecord-oracle_enhanced-adapter' => '~> 1.5.0'
   },
-  '4.2.8' => {
+  '4.2.10' => {
     'activerecord-oracle_enhanced-adapter' => '~> 1.6.0'
   },
-  '5.0.3' => {
+  '5.0.7' => {
     'activerecord-oracle_enhanced-adapter' => '~> 1.7.0',
     'ruby-oci8' => ''
   },
-  '5.1.1' => {
+  '5.1.6' => {
     'activerecord-oracle_enhanced-adapter' => '~> 1.8.0',
     'ruby-oci8' => ''
+  },
+  '5.2.0' => {
+    'activerecord-oracle_enhanced-adapter' => '~> 5.2.0',
+    'ruby-oci8' => ''
   }
-}
+}.freeze
 
 RAILS_VERSIONS.each do |version, gems|
   appraise "rails_#{version}" do
     gem 'rails', version
-    gems.each do |name, version|
-      if version.empty?
+    gems.each do |name, gem_version|
+      if gem_version.empty?
         gem name
       else
-        gem name, version
+        gem name, gem_version
       end
     end
   end

data/CHANGELOG.md

@@ -1,9 +1,30 @@
 # CHANGELOG
 
-## 0.3.1
+## 0.4.1 (2018-05-06)
+
+* Fix: Restore behavior of #filter method [Comment](https://github.com/jbox-web/ajax-datatables-rails/commit/07795fd26849ff1b3b567f4ce967f722907a45be#comments)
+* Fix: Fix erroneous offset/start behavior [PR #264](https://github.com/jbox-web/ajax-datatables-rails/pull/264)
+* Fix: "orderable" option has no effect [Issue #245](https://github.com/jbox-web/ajax-datatables-rails/issues/245)
+* Fix: Fix undefined method #and [PR #235](https://github.com/jbox-web/ajax-datatables-rails/pull/235)
+* Add: Add "order nulls last" option [PR #79](https://github.com/jbox-web/ajax-datatables-rails/pull/279)
+* Change: Rename `additional_datas` method as `additional_data` [PR #251](https://github.com/jbox-web/ajax-datatables-rails/pull/251)
+* Change: Added timezone support for daterange [PR #261](https://github.com/jbox-web/ajax-datatables-rails/pull/261)
+* Change: Add # frozen_string_literal: true pragma
+* Various improvements in internal API
+
+**Note :** This is the last version to support Rails 4.0.x and Rails 4.1.x
+
+
+## 0.4.0 (2017-05-21)
+
+**Warning:** this version is a **major break** from v0.3. The core has been rewriten to remove dependency on Kaminari (or WillPaginate).
+
+It also brings a new (more natural) way of defining columns, based on hash definitions (and not arrays) and add some filtering options for column search. Take a look at the [README](https://github.com/jbox-web/ajax-datatables-rails#customize-the-generated-datatables-class) for more infos.
+
+## 0.3.1 (2015-07-13)
 * Adds `:oracle` as supported `db_adapter`. Thanks to [lutechspa](https://github.com/lutechspa) for this contribution.
 
-## 0.3.0
+## 0.3.0 (2015-01-30)
 * Changes to the `sortable_columns` and `searchable_columns` syntax as it
   required us to do unnecessary guessing. New syntax is `ModelName.column_name`
   or `Namespace::ModelName.column_name`. Old syntax of `table_name.column_name`
@@ -14,7 +35,7 @@
   for this contribution.
 * Moves paginator settings to configuration initializer.
 
-## 0.2.1
+## 0.2.1 (2014-11-26)
 * Fix count method to work with select statements under Rails 4.1. Thanks to
 [Jason Mitchell](https://github.com/mitchej123) for the contribution.
 * Edits to `README` documentation about the `options` hash. Thanks to
@@ -32,22 +53,22 @@ text-based columns and perform searches depending on the use of `:mysql2`,
 `:sqlite3` or `:pg`. Thanks to [M. Saiqul Haq](https://github.com/saiqulhaq)
 for contributing this feature.
 
-## 0.2.0
+## 0.2.0 (2014-06-19)
 * This version works with jQuery dataTables ver. 1.10 and it's new API syntax.
 * Added `legacy` branch to repo. If your project is working with jQuery
   dataTables ver. 1.9, this is the branch you need to pull, or use the last
   `0.1.x` version of this gem.
 
-## 0.1.2
+## 0.1.2 (2014-06-18)
 * Fixes `where` clause being built even when search term is an empty string.
   Thanks to [e-fisher](https://github.com/e-fisher) for spotting and fixing this.
 
-## 0.1.1
+## 0.1.1 (2014-06-13)
 * Fixes problem on `searchable_columns` where the corresponding model is
 a composite model name, e.g. `UserData`, `BillingAddress`.
 Thanks to [iruca3](https://github.com/iruca3) for the fix.
 
-## 0.1.0
+## 0.1.0 (2014-05-21)
 * A fresh start. Sets base class name to: `AjaxDatatablesRails::Base`.
 * Extracts pagination functions to mixable modules.
   * A user would have the option to stick to the base
@@ -65,3 +86,7 @@ Thanks to [iruca3](https://github.com/iruca3) for the fix.
 * Sets generator inside the `Rails` namespace. To generate an
   `AjaxDatatablesRails` child class, just execute the
   generator like this: `$ rails generate datatable NAME`.
+
+## 0.0.1 (2012-09-10)
+
+First release!

data/Gemfile

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 source 'https://rubygems.org'
 
 gemspec

data/README.md

@@ -8,73 +8,138 @@
 [![Test Coverage](https://codeclimate.com/github/jbox-web/ajax-datatables-rails/badges/coverage.svg)](https://codeclimate.com/github/jbox-web/ajax-datatables-rails/coverage)
 [![Dependency Status](https://gemnasium.com/jbox-web/ajax-datatables-rails.svg)](https://gemnasium.com/jbox-web/ajax-datatables-rails)
 
-> __Important__
+**Important : This gem is targeted at DataTables version 1.10.x.**
+
+It's tested against :
+
+* Rails 4.0.13 / 4.1.16 / 4.2.10 / 5.0.7 / 5.1.6 / 5.2.0
+* Ruby 2.2.10 / 2.3.7 / 2.4.4 / 2.5.1
+* Postgresql 9.6
+* MySQL 5.6
+* Oracle XE 11.2 (thanks to [travis-oracle](https://github.com/cbandy/travis-oracle))
+* SQLite3
+
+## Description
+
+> [DataTables](https://datatables.net/) is a nifty jQuery plugin that adds the ability to paginate, sort, and search your html tables.
+> When dealing with large tables (more than a couple of hundred rows) however, we run into performance issues.
+> These can be fixed by using server-side pagination, but this breaks some DataTables functionality.
 >
-> This gem is targeted at Datatables version 1.10.x.
+> `ajax-datatables-rails` is a wrapper around DataTables ajax methods that allow synchronization with server-side pagination in a Rails app.
+> It was inspired by this [Railscast](http://railscasts.com/episodes/340-datatables).
+> I needed to implement a similar solution in a couple projects I was working on, so I extracted a solution into a gem.
 >
-> It's tested against :
-> * Rails 4.0.13 / 4.1.15 / 4.2.8 / 5.0.2 / 5.1.0
-> * Ruby 2.2.7 / 2.3.4 / 2.4.1
-> * Postgresql
-> * MySQL
-> * Oracle XE 11.2 (thanks to [travis-oracle](https://github.com/cbandy/travis-oracle))
+> Joel Quenneville (original author)
+>
+> I needed a good gem to manage a lot of DataTables so I chose this one :)
+>
+> Nicolas Rodriguez (current maintainer)
+
+The final goal of this gem is to **generate a JSON** content that will be given to jQuery DataTables.
+All the datatable customizations (header, tr, td, css classes, width, height, buttons, etc...) **must** take place in the [javascript definition](#5-wire-up-the-javascript) of the datatable.
+jQuery DataTables is a very powerful tool with a lot of customizations available. Take the time to [read the doc](https://datatables.net/reference/option/).
 
-## Description
 
-Datatables is a nifty jquery plugin that adds the ability to paginate, sort,
-and search your html tables. When dealing with large tables
-(more than a couple hundred rows) however, we run into performance issues.
-These can be fixed by using server-side pagination, but this breaks some
-datatables functionality.
+## Warning
 
-`ajax-datatables-rails` is a wrapper around datatable's ajax methods that allow
-synchronization with server-side pagination in a rails app. It was inspired by
-this [Railscast](http://railscasts.com/episodes/340-datatables). I needed to
-implement a similar solution in a couple projects I was working on, so I
-extracted a solution into a gem.
+**Breaking changes :** the *v0.4* version is a **major break** from *v0.3*.
 
-## ORM support
+The core has been rewriten to remove dependency on [Kaminari](https://github.com/kaminari/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
 
-Currently `AjaxDatatablesRails` only supports `ActiveRecord` as ORM for
-performing database queries.
+It also brings a new (more natural) way of defining columns, based on hash definitions (and not arrays) and add some filtering options for column search.
+
+[See below](#3-customize-the-generated-datatables-class) for more infos.
+
+To migrate on the v0.4 you'll need to :
+
+* update your DataTables classes to remove all the `extend` directives
+* switch to hash definitions of `view_columns`
+* update your views to declare your columns bindings ([See here](#5-wire-up-the-javascript))
 
-Adding support for `Sequel`, `Mongoid` and `MongoMapper` is a planned feature
-for this gem. If you'd be interested in contributing to speed development,
-please [open an issue](https://github.com/antillas21/ajax-datatables-rails/issues/new)
-and get in touch.
 
 ## Installation
 
 Add these lines to your application's Gemfile:
 
 ```ruby
-gem 'jquery-datatables-rails'
 gem 'ajax-datatables-rails'
 ```
 
 And then execute:
 
 ```sh
-$ bundle
+$ bundle install
 ```
 
-The `jquery-datatables-rails` gem is listed as a convenience, to ease adding
-jQuery dataTables to your Rails project. You can always add the plugin assets
-manually via the assets pipeline. If you decide to use the
-`jquery-datatables-rails` gem, please refer to its installation instructions
-[here](https://github.com/rweng/jquery-datatables-rails).
+We assume here that you have already installed [jQuery DataTables](https://datatables.net/).
+
+You can install jQuery DataTables :
+
+* with the [`jquery-datatables-rails`](https://github.com/rweng/jquery-datatables-rails) gem (which is a bit outdated)
+* by adding the assets manually (in `vendor/assets`)
+* with [Rails webpacker gem](https://github.com/rails/webpacker) (see [here](/doc/webpack.md) for more infos)
+
+
+## Configuration
+
+Generate the `ajax-datatables-rails` config file with this command :
+
+```sh
+$ bundle exec rails generate datatable:config
+```
+
+Doing so, will create the `config/initializers/ajax_datatables_rails.rb` file with the following content :
+
+```ruby
+AjaxDatatablesRails.configure do |config|
+  # available options for db_adapter are: :pg, :mysql, :mysql2, :sqlite, :sqlite3
+  # config.db_adapter = :pg
+
+  # Or you can use your rails environment adapter if you want a generic dev and production
+  # config.db_adapter = Rails.configuration.database_configuration[Rails.env]['adapter'].to_sym
+
+  # available options for orm are: :active_record, :mongoid
+  # config.orm = :active_record
+end
+```
+
+Uncomment the `config.db_adapter` line and set the corresponding value to your database and gem. This is all you need.
+
+Uncomment the `config.orm` line to set `active_record or mongoid` if included in your project. It defaults to `active_record`.
 
+#### Note
 
-## Usage
+Currently `AjaxDatatablesRails` only supports `ActiveRecord` as ORM for performing database queries.
 
-*The following examples assume that we are setting up ajax-datatables-rails for
-an index page of users from a `User` model, and that we are using postgresql as
-our db, because you __should be using it__, if not, please refer to the
-[Searching on non text-based columns](#searching-on-non-text-based-columns)
-entry in the Additional Notes section.*
+Adding support for `Sequel`, `Mongoid` and `MongoMapper` is (more or less) a planned feature for this gem.
 
+If you'd be interested in contributing to speed development, please [open an issue](https://github.com/antillas21/ajax-datatables-rails/issues/new) and get in touch.
 
-### Generate
+
+## Quick start (in 5 steps)
+
+The following examples assume that we are setting up `ajax-datatables-rails` for an index page of users from a `User` model,
+and that we are using Postgresql as our db, because you **should be using it**. (It also works with other DB, see above, just be sure to have [configured the right adapter](#configuration))
+
+The goal is to render a users table and display : `id`, `first name`, `last name`, `email`, and `bio` for each user.
+
+Something like this:
+
+|ID |First Name|Last Name|Email                 |Brief Bio|
+|---|----------|---------|----------------------|---------|
+| 1 |John      |Doe      |john.doe@example.net  |Is your default user everywhere|
+| 2 |Jane      |Doe      |jane.doe@example.net  |Is John's wife|
+| 3 |James     |Doe      |james.doe@example.net |Is John's brother and best friend|
+
+Here the steps we're going through :
+
+1. [Generate the datatable class](#1-generate-the-datatable-class)
+2. [Build the View](#2-build-the-view)
+3. [Customize the generated Datatables class](#3-customize-the-generated-datatables-class)
+4. [Setup the Controller action](#4-setup-the-controller-action)
+5. [Wire up the Javascript](#5-wire-up-the-javascript)
+
+### 1) Generate the datatable class
 
 Run the following command:
 
@@ -88,31 +153,24 @@ Open the file and customize in the functions as directed by the comments.
 Take a look [here](#generator-syntax) for an explanation about the generator syntax.
 
 
-### Build the View
-
-You should always start by the single source of truth, which is your html view. Suppose we need to render a users table and display: first name, last name, and bio for each user.
-
-Something like this:
-
-|First Name|Last Name|Brief Bio|
-|----------|---------|---------|
-|John      |Doe      |Is your default user everywhere|
-|Jane      |Doe      |Is John's wife|
-|James     |Doe      |Is John's brother and best friend|
+### 2) Build the View
 
+You should always start by the single source of truth, which is your html view.
 
 * Set up an html `<table>` with a `<thead>` and `<tbody>`
 * Add in your table headers if desired
-* Don't add any rows to the body of the table, datatables does this automatically
+* Don't add any rows to the body of the table, DataTables does this automatically
 * Add a data attribute to the `<table>` tag with the url of the JSON feed, in our case is the `users_path` as we're pointing to the `UsersController#index` action
 
 
 ```html
-<table id="users-table", data-source="<%= users_path(format: :json) %>">
+<table id="users-datatable" data-source="<%= users_path(format: :json) %>">
   <thead>
     <tr>
+      <th>ID</th>
       <th>First Name</th>
       <th>Last Name</th>
+      <th>Email</th>
       <th>Brief Bio</th>
     </tr>
   </thead>
@@ -122,25 +180,22 @@ Something like this:
 ```
 
 
-### Customize the generated Datatables class
+### 3) Customize the generated Datatables class
 
-```ruby
-def view_columns
-  # Declare strings in this format: ModelName.column_name
-  # or in aliased_join_table.column_name format
-  @view_columns ||= {}
-end
-```
+#### a. Declare columns mapping
 
-* In this method, add a list of the model(s) columns mapped to the data you need to present. In this case: `first_name`, `last_name` and `bio`.
+First we need to declare in `view_columns` the list of the model(s) columns mapped to the data we need to present.
+In this case: `id`, `first_name`, `last_name`, `email` and `bio`.
 
 This gives us:
 
 ```ruby
 def view_columns
   @view_columns ||= {
+    id:         { source: "User.id" },
     first_name: { source: "User.first_name", cond: :like, searchable: true, orderable: true },
     last_name:  { source: "User.last_name",  cond: :like },
+    email:      { source: "User.email" },
     bio:        { source: "User.bio" },
   }
 end
@@ -152,52 +207,32 @@ end
 
 * `:like`, `:start_with`, `:end_with` for string or full text search
 * `:eq`, `:not_eq`, `:lt`, `:gt`, `:lteq`, `:gteq`, `:in` for numeric
-* `:date_range` for date range (only for Rails > 4.2.x)
+* `:date_range` for date range (only for Rails > 4.2.x, see [here](#daterange-search))
 * `:null_value` for nil field
-* `Proc` for whatever
+* `Proc` for whatever (see [here](https://github.com/ajahongir/ajax-datatables-rails-v-0-4-0-how-to/blob/master/app/datatables/city_datatable.rb) for real example)
 
-[See here](#searching-on-non-text-based-columns) for notes about the `view_columns` settings (if using something different from `postgres`).
-[Read these notes](#columns-syntax) about considerations for the `view_columns` method.
+See [here](#columns-syntax) to get more details about columns definitions and how to play with associated models.
 
+#### b. Map data
 
-#### Map data
-
-```ruby
-def data
-  records.map do |record|
-    {
-      # a hash of key value pairs
-    }
-  end
-end
-```
+Then we need to map the records retrieved by the `get_raw_records` method to the real values we want to display :
 
 ```ruby
 def data
   records.map do |record|
     {
+      id:         record.id,
       first_name: record.first_name,
       last_name:  record.last_name,
+      email:      record.email,
       bio:        record.bio,
-      # 'DT_RowId' => record.id, # This will set the id attribute on the corresponding <tr> in the datatable
+      DT_RowId:   record.id, # This will set the id attribute on the corresponding <tr> in the datatable
     }
   end
 end
 ```
-
 You can either use the v0.3 Array style for your columns :
 
-```ruby
-def data
-  records.map do |record|
-    [
-      # comma separated list of the values for each cell of a table row
-      # example: record.first_name, record.last_name
-    ]
-  end
-end
-```
-
 This method builds a 2d array that is used by datatables to construct the html
 table. Insert the values you want on each column.
 
@@ -205,34 +240,27 @@ table. Insert the values you want on each column.
 def data
   records.map do |record|
     [
+      record.id,
       record.first_name,
       record.last_name,
+      record.email,
       record.bio
     ]
   end
 end
 ```
 
-[See here](#using-view-helpers) if you need to use view helpers like `link_to`, `mail_to`, `resource_path`, etc.
+The drawback of this method is that you can't pass the `DT_RowId` so it's tricky to set the id attribute on the corresponding `<tr>` in the datatable (need to be done on JS side).
 
+[See here](#using-view-helpers) if you need to use view helpers like `link_to`, `mail_to`, etc...
 
-#### Get Raw Records
-
-```ruby
-def get_raw_records
-  # insert query here
-end
-```
+#### c. Get Raw Records
 
 This is where your query goes.
 
 ```ruby
 def get_raw_records
-  # suppose we need all User records
-  # Rails 4+
   User.all
-  # Rails 3.x
-  # User.scoped
 end
 ```
 
@@ -246,105 +274,17 @@ def get_raw_records
 end
 ```
 
-You can put any logic in `get_raw_records` [based on any parameters you inject](#options) in the `Datatable` object.
-
-> __IMPORTANT:__ Make sure to return an `ActiveRecord::Relation` object
-> as the end product of this method.
->
-> Why? Because the result from this method, will be chained (for now)
-> to `ActiveRecord` methods for sorting, filtering and pagination.
-
+You can put any logic in `get_raw_records` [based on any parameters you inject](#pass-options-to-the-datatable-class) in the `Datatable` object.
 
-#### Associated and nested models
+**IMPORTANT :** Because the result of this method will be chained to `ActiveRecord` methods for sorting, filtering and pagination,
+make sure to return an `ActiveRecord::Relation` object.
 
-The previous example has only one single model. But what about if you have
-some associated nested models and in a report you want to show fields from
-these tables.
+#### d. Additional data
 
-Take an example that has an `Event, Course, Coursetype, Allocation, Teacher,
-Contact, Competency and CompetencyType` models. We want to have a datatables
-report which has the following column:
+You can inject other key/value pairs in the rendered JSON by defining the `#additional_data` method :
 
 ```ruby
-'coursetypes.name',
-'courses.name',
-'events.title',
-'events.event_start',
-'events.event_end',
-'contacts.full_name',
-'competency_types.name',
-'events.status'
-```
-
-We want to sort and search on all columns of the list. The related definition
-would be:
-
-```ruby
-def view_columns
-  @view_columns ||= [
-    'Coursetype.name',
-    'Course.name',
-    'Event.title',
-    'Event.event_start',
-    'Event.event_end',
-    'Contact.last_name',
-    'CompetencyType.name',
-    'Event.status'
-  ]
-end
-
-def get_raw_records
-   Event.joins(
-    { course: :coursetype },
-    { allocations: {
-        teacher: [:contact, {competencies: :competency_type}]
-      }
-    }).distinct
-end
-```
-
-__Some comments for the above code:__
-
-1. In the `get_raw_records` method we have quite a complex query having one to
-many and may to many associations using the joins ActiveRecord method.
-The joins will generate INNER JOIN relations in the SQL query. In this case,
-we do not include all event in the report if we have events which is not
-associated with any model record from the relation.
-
-2. To have all event records in the list we should use the `.includes` method,
-which generate LEFT OUTER JOIN relation of the SQL query.
-__IMPORTANT:__ Make sure to append `.references(:related_model)` with any
-associated model. That forces the eager loading of all the associated models
-by one SQL query, and the search condition for any column works fine.
-Otherwise the `:recordsFiltered => filter_records(get_raw_records).count(:all)`
-will generate 2 SQL queries (one for the Event model, and then another for the
-associated tables). The `:recordsFiltered => filter_records(get_raw_records).count(:all)`
-will use only the first one to return from the ActiveRecord::Relation object
-in `get_raw_records` and you will get an error message of __Unknown column
-'yourtable.yourfield' in 'where clause'__ in case the search field value
-is not empty.
-
-So the query using the `.includes()` method is:
-
-```ruby
-def get_raw_records
-   Event.includes(
-    { course: :coursetype },
-    { allocations: {
-        teacher: [:contact, { competencies: :competency_type }]
-      }
-    }
-    ).references(:course).distinct
-end
-```
-
-
-#### Additional datas
-
-You can inject other key/value pairs in the rendered JSON by defining the `#additional_datas` method :
-
-```ruby
-def additional_datas
+def additional_data
   {
     foo: 'bar'
   }
@@ -354,7 +294,7 @@ end
 Very useful with https://github.com/vedmack/yadcf to provide values for dropdown filters.
 
 
-### Setup the Controller action
+### 4) Setup the Controller action
 
 Set the controller to respond to JSON
 
@@ -369,9 +309,9 @@ end
 
 Don't forget to make sure the proper route has been added to `config/routes.rb`.
 
-[See here](#options) to inject params in the `UserDatatable`.
+[See here](#pass-options-to-the-datatable-class) if you need to inject params in the `UserDatatable`.
 
-### Wire up the Javascript
+### 5) Wire up the Javascript
 
 Finally, the javascript to tie this all together. In the appropriate `coffee` file:
 
@@ -379,217 +319,307 @@ Finally, the javascript to tie this all together. In the appropriate `coffee` fi
 # users.coffee
 
 $ ->
-  $('#users-table').dataTable
+  $('#users-datatable').dataTable
     processing: true
     serverSide: true
-    ajax: $('#users-table').data('source')
+    ajax: $('#users-datatable').data('source')
     pagingType: 'full_numbers'
-    # optional, if you want full pagination controls.
+    columns: [
+      {data: 'id'}
+      {data: 'first_name'}
+      {data: 'last_name'}
+      {data: 'email'}
+      {data: 'bio'}
+    ]
+    # pagingType is optional, if you want full pagination controls.
     # Check dataTables documentation to learn more about
     # available options.
 ```
 
 or, if you're using plain javascript:
+
 ```javascript
 // users.js
 
 jQuery(document).ready(function() {
-  $('#users-table').dataTable({
+  $('#users-datatable').dataTable({
     "processing": true,
     "serverSide": true,
-    "ajax": $('#users-table').data('source'),
+    "ajax": $('#users-datatable').data('source'),
     "pagingType": "full_numbers",
-    // optional, if you want full pagination controls.
+    "columns": [
+      {"data": "id"},
+      {"data": "first_name"},
+      {"data": "last_name"},
+      {"data": "email"},
+      {"data": "bio"}
+    ]
+    // pagingType is optional, if you want full pagination controls.
     // Check dataTables documentation to learn more about
     // available options.
   });
 });
 ```
 
+## Advanced usage
 
-### Additional Notes
-
-#### Columns syntax
+### Using view helpers
 
-Since version `0.3.0`, we are implementing a pseudo code way of declaring
-the array columns to use when querying the database.
+Sometimes you'll need to use view helper methods like `link_to`, `mail_to`,
+`edit_user_path`, `check_box_tag` and so on in the returned JSON representation returned by the [`data`](#b-map-data) method.
 
-Example. Suppose we have the following models: `User`, `PurchaseOrder`,
-`Purchase::LineItem` and we need to have several columns from those models
-available in our datatable to search and sort by.
+To have these methods available to be used, this is the way to go:
 
 ```ruby
-# we use the ModelName.column_name notation to declare our columns
-
-def view_columns
-  @view_columns ||= [
-    'User.first_name',
-    'User.last_name',
-    'PurchaseOrder.number',
-    'PurchaseOrder.created_at',
-    'Purchase::LineItem.quantity',
-    'Purchase::LineItem.unit_price',
-    'Purchase::LineItem.item_total'
-  ]
-end
-```
-
+class MyCustomDatatable < AjaxDatatablesRails::Base
+  # either define them one-by-one
+  def_delegator :@view, :check_box_tag
+  def_delegator :@view, :link_to
+  def_delegator :@view, :mail_to
+  def_delegator :@view, :edit_user_path
 
-#### What if the datatable itself is namespaced?
+  # or define them in one pass
+  def_delegators :@view, :check_box_tag, :link_to, :mail_to, :edit_user_path
 
-Example: what if the datatable is namespaced into an `Admin` module?
+  # ... other methods (view_columns, get_raw_records...)
 
-```ruby
-module Admin
-  class PurchasesDatatable < AjaxDatatablesRails::Base
+  # now, you'll have these methods available to be used anywhere
+  def data
+    records.map do |record|
+      {
+        id:         check_box_tag('users[]', record.id),
+        first_name: link_to(record.first_name, edit_user_path(record)),
+        last_name:  record.last_name,
+        email:      mail_to(record.email),
+        bio:        record.bio
+        DT_RowId:   record.id,
+      }
+    end
   end
 end
 ```
 
-Taking the same models and columns, we would define it like this:
+If you want to keep things tidy in the data mapping method, you could use
+[Draper](https://github.com/drapergem/draper) to define column mappings like below.
+
+Example :
 
 ```ruby
-def view_columns
-  @view_columns ||= [
-    '::User.first_name',
-    '::User.last_name',
-    '::PurchaseOrder.number',
-    '::PurchaseOrder.created_at',
-    '::Purchase::LineItem.quantity',
-    '::Purchase::LineItem.unit_price',
-    '::Purchase::LineItem.item_total'
-  ]
-end
-```
+...
+  def data
+    records.map do |record|
+      {
+        id:         record.decorate.check_box,
+        first_name: record.decorate.link_to,
+        last_name:  record.decorate.last_name
+        email:      record.decorate.email,
+        bio:        record.decorate.bio
+        DT_RowId:   record.id,
+      }
+    end
+  end
+...
 
-Pretty much like you would do it, if you were inside a namespaced controller.
+class UserDecorator < ApplicationDecorator
+  delegate :last_name, :bio
 
+  def check_box
+    h.check_box_tag 'users[]', object.id
+  end
 
-#### Searching on non text-based columns
+  def link_to
+    h.link_to object.first_name, h.edit_user_path(object)
+  end
 
-It always comes the time when you need to add a non-string/non-text based
-column to the `@view_columns` array, so you can perform searches against
-these column types (example: numeric, date, time).
+  def email
+    h.mail_to object.email
+  end
 
-We recently added the ability to (automatically) typecast these column types
-and have this scenario covered. Please note however, if you are using
-something different from `postgresql` (with the `:pg` gem), like `mysql` or
-`sqlite`, then you need to add an initializer in your application's
-`config/initializers` directory.
+  # Just an example of a complex method you can add to you decorator
+  # To render it in a datatable just add a column 'dt_actions' in
+  # 'view_columns' and 'data' methods and call record.decorate.dt_actions
+  def dt_actions
+    links = []
+    links << h.link_to 'Edit',   h.edit_user_path(object) if h.policy(object).update?
+    links << h.link_to 'Delete', h.user_path(object), method: :delete, remote: true if h.policy(object).destroy?
+    h.safe_join(links, '')
+  end
+end
+```
 
-If you don't perform this step (again, if using something different from
-`postgresql`), your database will complain that it does not understand the
-default typecast used to enable such searches.
+**Note :** On the long term it's much more cleaner than using `def_delegator` since decorators are reusable everywhere in your application :)
 
+So we **strongly recommand you to use Draper decorators.** It will help keeping your DataTables class small and clean and keep focused on what they should do (mostly) : filtering records ;)
 
-#### Configuration initializer
+**Note 2 :** The `def_delegator` might disappear in a near future : [#288 [RFC] Remove dependency on view_context](https://github.com/jbox-web/ajax-datatables-rails/issues/288).
+You're invited to give your opinion :)
 
-You have two options to create this initializer:
+### Pass options to the datatable class
 
-* use the provided (and recommended) generator (and then just edit the file);
-* create the file from scratch.
+An `AjaxDatatablesRails::Base` inherited class can accept an options hash at initialization. This provides room for flexibility when required.
 
-To use the generator, from the terminal execute:
+Example:
 
-```sh
-$ bundle exec rails generate datatable:config
-```
+```ruby
+# In the controller
+def index
+  respond_to do |format|
+    format.html
+    format.json { render json: UserDatatable.new(view_context, user: current_user, from: 1.month.ago) }
+  end
+end
 
-Doing so, will create the `config/initializers/ajax_datatables_rails.rb` file
-with the following content:
+# The datatable class
+class UnrespondedMessagesDatatable < AjaxDatatablesRails::Base
 
-```ruby
-AjaxDatatablesRails.configure do |config|
-  # available options for db_adapter are: :pg, :mysql, :mysql2, :sqlite, :sqlite3
-  # config.db_adapter = :pg
+  # ... other methods (view_columns, data...)
 
-  # available options for orm are: :active_record, :mongoid
-  # config.orm = :active_record
-end
-```
+  def user
+    @user ||= options[:user]
+  end
 
-Uncomment the `config.db_adapter` line and set the corresponding value to your
-database and gem. This is all you need.
+  def from
+    @from ||= options[:from].beginning_of_day
+  end
 
-Uncomment the `config.orm` line to set `active_record or mongoid` if
-included in your project. It defaults to `active_record`.
+  def to
+    @to ||= Date.today.end_of_day
+  end
 
-If you want to make the file from scratch, just copy the above code block into
-a file inside the `config/initializers` directory.
+  # We can now customize the get_raw_records method
+  # with the options we've injected
+  def get_raw_records
+    user.messages.unresponded.where(received_at: from..to)
+  end
 
+end
+```
 
-#### Using view helpers
+### Columns syntax
 
-Sometimes you'll need to use view helper methods like `link_to`, `h`, `mailto`,
-`edit_resource_path` in the returned JSON representation returned by the `data`
-method.
+You can mix several model in the same datatable.
 
-To have these methods available to be used, this is the way to go:
+Suppose we have the following models: `User`, `PurchaseOrder`,
+`Purchase::LineItem` and we need to have several columns from those models
+available in our datatable to search and sort by.
 
 ```ruby
-class MyCustomDatatable < AjaxDatatablesRails::Base
-  # either define them one-by-one
-  def_delegator :@view, :link_to
-  def_delegator :@view, :h
-  def_delegator :@view, :mail_to
-
-  # or define them in one pass
-  def_delegators :@view, :link_to, :h, :mailto, :edit_resource_path, :other_method
+# we use the ModelName.column_name notation to declare our columns
 
-  # now, you'll have these methods available to be used anywhere
-  # example: mapping the 2d jsonified array returned.
-  def data
-    records.map do |record|
-      {
-        first_name: link_to(record.fname, edit_resource_path(record)),
-        email:      mail_to(record.email),
-        # other attributes
-      }
-    end
-  end
+def view_columns
+  @view_columns ||= {
+    first_name:       'User.first_name',
+    last_name:        'User.last_name',
+    order_number:     'PurchaseOrder.number',
+    order_created_at: 'PurchaseOrder.created_at',
+    quantity:         'Purchase::LineItem.quantity',
+    unit_price:       'Purchase::LineItem.unit_price',
+    item_total:       'Purchase::LineItem.item_total'
+  }
 end
 ```
 
+### Associated and nested models
 
-#### Options
+The previous example has only one single model. But what about if you have
+some associated nested models and in a report you want to show fields from
+these tables.
 
-An `AjaxDatatablesRails::Base` inherited class can accept an options hash at
-initialization. This provides room for flexibility when required. Example:
+Take an example that has an `Event, Course, CourseType, Allocation, Teacher,
+Contact, Competency and CompetencyType` models. We want to have a datatables
+report which has the following column:
 
 ```ruby
-class UnrespondedMessagesDatatable < AjaxDatatablesRails::Base
-  # customized methods here
-end
-
-datatable = UnrespondedMessagesDatatable.new(view_context,
-  { user: current_user, from: 1.month.ago }
-)
+'course_types.name'
+'courses.name'
+'contacts.full_name'
+'competency_types.name'
+'events.title'
+'events.event_start'
+'events.event_end'
+'events.status'
 ```
 
-So, now inside your class code, you can use those options like this:
-
+We want to sort and search on all columns of the list.
+The related definition would be :
 
 ```ruby
-# let's see an example
-def user
-  @user ||= options[:user]
+def view_columns
+  @view_columns ||= {
+    course_type:     'CourseType.name',
+    course_name:     'Course.name',
+    contact_name:    'Contact.full_name',
+    competency_type: 'CompetencyType.name',
+    event_title:     'Event.title',
+    event_start:     'Event.event_start',
+    event_end:       'Event.event_end',
+    event_status:    'Event.status',
+  }
 end
 
-def from
-  @from ||= options[:from].beginning_of_day
+def get_raw_records
+  Event.joins(
+    { course: :course_type },
+    { allocations: {
+      teacher: [:contact, { competencies: :competency_type }]
+    }
+  }).distinct
 end
+```
 
-def to
-  @to ||= Date.today.end_of_day
-end
+**Some comments for the above code :**
+
+1. In the `get_raw_records` method we have quite a complex query having one to
+many and many to many associations using the joins ActiveRecord method.
+The joins will generate INNER JOIN relations in the SQL query. In this case,
+we do not include all event in the report if we have events which is not
+associated with any model record from the relation.
+
+2. To have all event records in the list we should use the `.includes` method,
+which generate LEFT OUTER JOIN relation of the SQL query.
 
+**IMPORTANT :**
+
+Make sure to append `.references(:related_model)` with any
+associated model. That forces the eager loading of all the associated models
+by one SQL query, and the search condition for any column works fine.
+Otherwise the `:recordsFiltered => filter_records(get_raw_records).count(:all)`
+will generate 2 SQL queries (one for the Event model, and then another for the
+associated tables). The `:recordsFiltered => filter_records(get_raw_records).count(:all)`
+will use only the first one to return from the ActiveRecord::Relation object
+in `get_raw_records` and you will get an error message of **Unknown column
+'yourtable.yourfield' in 'where clause'** in case the search field value
+is not empty.
+
+So the query using the `.includes()` method is:
+
+```ruby
 def get_raw_records
-  user.messages.unresponded.where(received_at: from..to)
+  Event.includes(
+    { course: :course_type },
+    { allocations: {
+      teacher: [:contact, { competencies: :competency_type }]
+    }
+  }).references(:course).distinct
 end
 ```
 
+### Default scope
+
+See [DefaultScope is evil](https://rails-bestpractices.com/posts/2013/06/15/default_scope-is-evil/) and [#223](https://github.com/jbox-web/ajax-datatables-rails/issues/223) and [#233](https://github.com/jbox-web/ajax-datatables-rails/issues/233).
+
+### DateRange search
+
+This feature works with [yadcf](https://github.com/vedmack/yadcf).
 
-#### Generator Syntax
+To enable the date range search, for example `created_at` :
+
+* add a 'created_at' `<th>` in your html
+* declare your column in `view_columns` : `created_at: { source: 'Post.created_at', cond: :date_range, delimiter: '-yadcf_delim-' }`
+* add it in `data` : `created_at: record.decorate.created_at`
+* setup yadcf to make `created_at` search field a range
+
+### Generator Syntax
 
 Also, a class that inherits from `AjaxDatatablesRails::Base` is not tied to an
 existing model, module, constant or any type of class in your Rails app.
@@ -611,19 +641,54 @@ In the end, it's up to the developer which model(s), scope(s), relationship(s)
 (or else) to employ inside the datatable class to retrieve records from the
 database.
 
+### Creating indices for Postgresql
 
-## Tutorial
+In order to speed up the `ILIKE` queries that are executed when using the default configuration, you might want to consider adding some indices.
+For postgresql, you are advised to use the [gin/gist index type](http://www.postgresql.org/docs/current/interactive/pgtrgm.html).
+This makes it necessary to enable the postgrsql extension `pg_trgm`. Double check that you have this extension installed before trying to enable it.
+A migration for enabling the extension and creating the indices could look like this:
 
-Tutorial for Integrating `ajax-datatables-rails` on  Rails 4.
+```ruby
+def change
+  enable_extension :pg_trgm
+  TEXT_SEARCH_ATTRIBUTES = ['your', 'attributes']
+  TABLE = 'your_table'
+
+  TEXT_SEARCH_ATTRIBUTES.each do |attr|
+    reversible do |dir|
+      dir.up do
+        execute "CREATE INDEX #{TABLE}_#{attr}_gin ON #{TABLE} USING gin(#{attr} gin_trgm_ops)"
+      end
+
+      dir.down do
+        remove_index TABLE.to_sym, name: "#{TABLE}_#{attr}_gin"
+      end
+    end
+  end
+end
+```
 
-[Part-1  The-Installation](https://github.com/jbox-web/ajax-datatables-rails/wiki/Part-1----The-Installation)
+### Speedup JSON rendering
 
-[Part 2 The Datatables with ajax functionality](https://github.com/jbox-web/ajax-datatables-rails/wiki/Part-2-The-Datatables-with-ajax-functionality)
+Install [yajl-ruby](https://github.com/brianmario/yajl-ruby), basically :
 
-The complete project code for this tutorial series is available on [github](https://github.com/trkrameshkumar/simple_app).
+```ruby
+gem 'yajl-ruby', require: 'yajl'
+```
+
+then
+
+```sh
+$ bundle install
+```
+
+That's all :) ([Automatically prefer Yajl or JSON backend over Yaml, if available](https://github.com/rails/rails/commit/63bb955a99eb46e257655c93dd64e86ebbf05651))
+
+## Tutorial
 
-Another sample project [code](https://github.com/ajahongir/ajax-datatables-rails-v-0-4-0-how-to). Its real world example.
+You'll find a sample project [here](https://github.com/ajahongir/ajax-datatables-rails-v-0-4-0-how-to). Its real world example.
 
+Filtering by JSONB column values : [#277](https://github.com/jbox-web/ajax-datatables-rails/issues/277)
 
 ## Contributing