ajax-datatables-rails 0.2.1 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4dd7a0250f12d3ba425ebbadceec912cd9b5c8e3
-  data.tar.gz: 0f70205e103b95e91970f1a29c9da2149b52b9d2
+  metadata.gz: fb40ce5ae30557f81c8a63451ab50f2e4c23c5f3
+  data.tar.gz: bad6eea562962c847c1b3cec96e83b65e950735a
 SHA512:
-  metadata.gz: 7b88ac6e283edd40600632948dc002a7d4361052dc611a0b87997145fb100c92e15652f2a10c7f0fb0c8d76708a78bd3df407f8d822e321b2a7c35171b195f9f
-  data.tar.gz: 442c3da29cddba54dc636b7ce2b325f5a0ef504b12b1994cb9150ce044ba2c8e40360b18b462ab5e5de9300ee57ef7d36aa0ae2ac53714ed7377461bcb125abd
+  metadata.gz: 9af79c2aa217a781f1f9fcad0eec6071ecd81ad4c350cd4ef60c3e74642f7e955988d54cd90e2085aeb8ca76d0536317e53bd422da4971216a8b801630c6e9b0
+  data.tar.gz: e840e32893f670972bc292788295fe18a713fa016b25327ef94eaeabaa0914b34f12d7c0df32f2f59d1a4affbc32cd01c16d0dd52f45818cc4e2b40e8e50c064

data/CHANGELOG.md

@@ -1,12 +1,33 @@
 # CHANGELOG
 
+## 0.3.0 (unreleased yet)
+* 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`
+  is still available to use, but prints a deprecation warning. Thanks to
+  [M. Saiqul Haq](https://github.com/saiqulhaq) for pointing this.
+* Adds support to discover from received params if a column should be really
+  considered for sorting purposes. Thanks to [Zachariah Clay](https://github.com/mebezac)
+  for this contribution.
+* Moves paginator settings to configuration initializer.
+
 ## 0.2.1
-* 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 [Jonathan E Hogue](https://github.com/hoguej) for pointing out that previous documentation was confusing and didn't address its usage properly.
-* Edits to `README` documentation on complex model queries inside the `get_raw_records` method. A round of applause to [Zoltan Paulovics](https://github.com/zpaulovics) for contributing this awesome piece of documentation. :smile:
-* Adds typecast step to `search_condition` method, so now we support having non-text columns inside the `searchable_columns` array.
-* Adds support for multi-column sorting and multi-term search. Thanks to [Zoltan Paulovics](https://github.com/zpaulovics) for contributing this feature.
-* Adds optional config initializer, so we can have a base to typecast non 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.
+* 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
+[Jonathan E Hogue](https://github.com/hoguej) for pointing out that previous
+documentation was confusing and didn't address its usage properly.
+* Edits to `README` documentation on complex model queries inside the
+`get_raw_records` method. A round of applause to [Zoltan Paulovics](https://github.com/zpaulovics)
+for contributing this awesome piece of documentation. :smile:
+* Adds typecast step to `search_condition` method, so now we support having
+non-text columns inside the `searchable_columns` array.
+* Adds support for multi-column sorting and multi-term search. Thanks to
+[Zoltan Paulovics](https://github.com/zpaulovics) for contributing this feature.
+* Adds optional config initializer, so we can have a base to typecast non
+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
 * This version works with jQuery dataTables ver. 1.10 and it's new API syntax.
@@ -29,12 +50,15 @@ Thanks to [iruca3](https://github.com/iruca3) for the fix.
   * A user would have the option to stick to the base
     `AjaxDatatablesRails::Extensions::SimplePaginator` or replace it with
     `AjaxDatatablesRails::Extensions::Kaminari` or
-    `AjaxDatatablesRails::Extensions::WillPaginate`, depending on what he/she is using to handle record pagination.
+    `AjaxDatatablesRails::Extensions::WillPaginate`, depending on what he/she
+    is using to handle record pagination.
 * Removes dependency to pass in a model name to the generator. This way,
-  the developer has more flexibility to implement whatever datatable feature is required.
+  the developer has more flexibility to implement whatever datatable feature is
+  required.
 * Datatable constructor accepts an optional `options` hash to provide
   more flexibility.
-  See [README](https://github.com/antillas21/ajax-datatables-rails/blob/master/README.mds#options) for examples.
+  See [README](https://github.com/antillas21/ajax-datatables-rails/blob/master/README.mds#options)
+  for examples.
 * Sets generator inside the `Rails` namespace. To generate an
   `AjaxDatatablesRails` child class, just execute the
   generator like this: `$ rails generate datatable NAME`.

data/README.md

@@ -6,9 +6,11 @@
 
 ### Versions
 
-[Datatables](http://datatables.net) recently released version 1.10 and deprecated version 1.9 which includes a new API and features.
+[Datatables](http://datatables.net) recently released version 1.10 (which
+includes a new API and features) and deprecated version 1.9.
 
-If you have dataTables 1.9 in your project and want to keep using it, please use this gem's version `0.1.x` in your `Gemfile`:
+If you have dataTables 1.9 in your project and want to keep using it, please
+use this gem's version `0.1.x` in your `Gemfile`:
 
 ```ruby
 # specific version number
@@ -18,21 +20,33 @@ gem 'ajax-datatables-rails', '0.1.2'
 gem 'ajax-datatables-rails', git: 'git://github.com/antillas21/ajax-datatables-rails.git', branch: 'legacy'
 ```
 
-If you have dataTables 1.10 in your project, then use the gem's latest version, or point to the `master` branch.
-
+If you have dataTables 1.10 in your project, then use the gem's latest version,
+or point to the `master` branch.
 
 
 ## 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.
+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.
 
-`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 it out into a gem.
+`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.
 
 ## ORM support
 
-Currently `AjaxDatatablesRails` only supports `ActiveRecord` as ORM for performing database queries.
+Currently `AjaxDatatablesRails` only supports `ActiveRecord` as ORM for
+performing database queries.
 
-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.
+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
 
@@ -47,11 +61,16 @@ And then execute:
 
 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).
+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).
 
 ## Usage
-*The following examples assume that we are setting up ajax-datatables-rails for an index 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.*
+*The following examples assume that we are setting up ajax-datatables-rails for
+an index 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.*
 
 ### Generate
 Run the following command:
@@ -59,38 +78,32 @@ Run the following command:
     $ rails generate datatable User
 
 
-This will generate a file named `user_datatable.rb` in `app/datatables`. Open the file and customize in the functions as directed by the comments.
+This will generate a file named `user_datatable.rb` in `app/datatables`.
+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.
 
 ### Customize
 ```ruby
-# uncomment the appropriate paginator module,
-# depending on gems available in your project.
-# include AjaxDatatablesRails::Extensions::Kaminari
-# include AjaxDatatablesRails::Extensions::WillPaginate
-# include AjaxDatatablesRails::Extensions::SimplePaginator
-
 def sortable_columns
-  # list columns inside the Array in string dot notation.
-  # Example: 'users.email'
+  # Declare strings in this format: ModelName.column_name
   @sortable_columns ||= []
 end
 
 def searchable_columns
-  # list columns inside the Array in string dot notation.
-  # Example: 'users.email'
+  # Declare strings in this format: ModelName.column_name
   @searchable_columns ||= []
 end
 ```
 
-* For `paginator options`, just uncomment the paginator you would like to use, given
-the gems bundled in your project. For example, if your models are using `Kaminari`, uncomment `AjaxDatatablesRails::Extensions::Kaminari`. You may remove all commented lines.
-  * `SimplePaginator` is the most basic of them all, it falls back to passing `offset` and `limit` at the database level (through `ActiveRecord` of course, as that is the only ORM supported for the time being).
+* For `sortable_columns`, assign an array of the database columns that
+correspond to the columns in our view table. For example
+`[users.f_name, users.l_name, users.bio]`. This array is used for sorting by
+various columns.
 
-* For `sortable_columns`, assign an array of the database columns that correspond to the columns in our view table. For example `[users.f_name, users.l_name, users.bio]`. This array is used for sorting by various columns.
-
-* For `searchable_columns`, assign an array of the database columns that you want searchable by datatables. For example `[users.f_name, users.l_name]`
+* For `searchable_columns`, assign an array of the database columns that you
+want searchable by datatables. Suppose we need to sort and search users
+`:first_name`, `last_name` and `bio`.
 
 This gives us:
 
@@ -98,15 +111,22 @@ This gives us:
 include AjaxDatatablesRails::Extensions::Kaminari
 
 def sortable_columns
-  @sortable_columns ||= ['users.f_name', 'users.l_name', 'users.bio']
+  @sortable_columns ||= %w(User.first_name User.last_name User.bio)
+  # this is equal to:
+  # @sortable_columns ||= ['User.first_name', 'User.last_name', 'User.bio']
 end
 
 def searchable_columns
-  @searchable_columns ||= ['users.f_name', 'users.l_name']
+  @searchable_columns ||= %w(User.first_name User.last_name User.bio)
+  # this is equal to:
+  # @searchable_columns ||= ['User.first_name', 'User.last_name', 'User.bio']
 end
 ```
 
-[See here](#searching-on-non-text-based-columns) for notes regarding database config (if using something different from `postgre`).
+* [See here](#searching-on-non-text-based-columns) for notes about the
+`searchable_columns` settings (if using something different from `postgre`).
+* [Read these notes](#searchable-and-sortable-columns-syntax) about
+considerations for the `searchable_columns` and `sortable_columns` methods.
 
 ### Map data
 ```ruby
@@ -120,21 +140,23 @@ def data
 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.
+This method builds a 2d array that is used by datatables to construct the html
+table. Insert the values you want on each column.
 
 ```ruby
 def data
   records.map do |record|
     [
-      record.f_name,
-      record.l_name,
+      record.first_name,
+      record.last_name,
       record.bio
     ]
   end
 end
 ```
 
-[See here](#using-view-helpers) if you need to use view helpers in the returned 2d array, like `link_to`, `mail_to`, `resource_path`, etc.
+[See here](#using-view-helpers) if you need to use view helpers in the
+returned 2d array, like `link_to`, `mail_to`, `resource_path`, etc.
 
 #### Get Raw Records
 ```ruby
@@ -147,18 +169,31 @@ 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
 ```
 
-Obviously, you can construct your query as required for the use case the datatable is used. Example: `User.active.with_recent_messages`.
-__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.
+Obviously, you can construct your query as required for the use case the
+datatable is used. Example: `User.active.with_recent_messages`.
+
+__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.
 
 #### Associated and nested models
-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.
+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.
+
+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:
 
-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
         'coursetypes.name',
         'courses.name',
@@ -169,32 +204,35 @@ Take an example that has an `Event, Course, Coursetype, Allocation, Teacher, Con
         'competency_types.name',
         'events.status'
 ```
-We want to sort and search on all columns of the list. The related definition would be:
+
+We want to sort and search on all columns of the list. The related definition
+would be:
+
 ```ruby
 
   def sortable_columns
     @sortable_columns ||= [
-        'coursetypes.name',
-        'courses.name',
-        'events.title',
-        'events.event_start',
-        'events.event_end',
-        'contacts.last_name',
-        'competency_types.name',
-        'events.status'
+        'Coursetype.name',
+        'Course.name',
+        'Event.title',
+        'Event.event_start',
+        'Event.event_end',
+        'Contact.last_name',
+        'CompetencyType.name',
+        'Event.status'
     ]
   end
 
   def searchable_columns
     @searchable_columns ||= [
-        'coursetypes.name',
-        'courses.name',
-        'events.title',
-        'events.event_start',
-        'events.event_end',
-        'contacts.last_name',
-        'competency_types.name',
-        'events.status'
+        'Coursetype.name',
+        'Course.name',
+        'Event.title',
+        'Event.event_start',
+        'Event.event_end',
+        'Contact.last_name',
+        'CompetencyType.name',
+        'Event.status'
     ]
   end
 
@@ -210,11 +248,29 @@ We want to sort and search on all columns of the list. The related definition wo
 
 __Some comments for the above code:__
 
-1. In the list we show `full_name`, but in `sortable_columns` and `searchable_columns` we use `last_name` from the `Contact` model. The reason is we can use only database columns as sort or search fields and the full_name is not a database field.
-
-2. 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.
-
-3. 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.
+1. In the list we show `full_name`, but in `sortable_columns` and
+`searchable_columns` we use `last_name` from the `Contact` model. The reason
+is we can use only database columns as sort or search fields and the full_name
+is not a database field.
+
+2. 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.
+
+3. 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:
 
@@ -230,6 +286,7 @@ So the query using the `.includes()` method is:
   end
 ```
 
+
 ### Controller
 Set up the controller to respond to JSON
 
@@ -244,7 +301,9 @@ end
 
 Don't forget to make sure the proper route has been added to `config/routes.rb`.
 
+
 ### 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
@@ -252,7 +311,7 @@ Don't forget to make sure the proper route has been added to `config/routes.rb`.
 
 The resulting view may look like this:
 
-```erb
+```html
 <table id="users-table", data-source="<%= users_path(format: :json) %>">
   <thead>
     <tr>
@@ -267,9 +326,11 @@ The resulting view may look like this:
 ```
 
 ### Javascript
-Finally, the javascript to tie this all together. In the appropriate `js.coffee` file:
+Finally, the javascript to tie this all together. In the appropriate `coffee` file:
 
 ```coffeescript
+# users.coffee
+
 $ ->
   $('#users-table').dataTable
     processing: true
@@ -300,13 +361,86 @@ jQuery(document).ready(function() {
 
 ### Additional Notes
 
+#### Searchable and Sortable columns syntax
+
+Starting on version `0.3.0`, we are implementing a pseudo code way of declaring
+the array of both `searchable_columns` and `sortable_columns` 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.
+
+```ruby
+# we use the ModelName.column_name notation to declare our columns
+
+def searchable_columns
+  @searchable_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 sortable_columns
+  @sortable_columns ||= [
+    'User.first_name',
+    'User.last_name',
+    'PurchaseOrder.number',
+    'PurchaseOrder.created_at'
+  ]
+end
+```
+
+##### What if the datatable itself is namespaced?
+Example: what if the datatable is namespaced into an `Admin` module?
+
+```ruby
+module Admin
+  class PurchasesDatatable < AjaxDatatablesRails::Base
+  end
+end
+```
+
+Taking the same models and columns, we would define it like this:
+
+```ruby
+def searchable_columns
+  @searchable_columns ||= [
+    '::User.first_name',
+    '::User.last_name',
+    '::PurchaseOrder.number',
+    '::PurchaseOrder.created_at',
+    '::Purchase::LineItem.quantity',
+    '::Purchase::LineItem.unit_price',
+    '::Purchase::LineItem.item_total'
+  ]
+end
+```
+
+Pretty much like you would do it, if you were inside a namespaced controller.
+
 #### Searching on non text-based columns
 
-It always comes the time when you need to add a non-string/non-text based column to the `@searchable_columns` array, so you can perform searches against these column types (example: numeric, date, time).
+It always comes the time when you need to add a non-string/non-text based
+column to the `@searchable_columns` array, so you can perform searches against
+these column types (example: numeric, date, time).
+
+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.
 
-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 `postgre` (with the `:pg` gem), like `mysql` or `sqlite`, then you need to add an initializer in your application's `config/initializers` directory.
+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.
 
-If you don't perform this step (again, if using something different from `postgre`), your database will complain that it does not understand the default typecast used to enable such searches.
+
+#### Configuration initializer
 
 You have two options to create this initializer:
 
@@ -319,24 +453,36 @@ To use the generator, from the terminal execute:
 $ bundle exec rails generate datatable:config
 ```
 
-Doing so, will create the `config/initializers/ajax_datatables_rails.rb` file with the following content:
+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, :mysql2, :sqlite3
   # config.db_adapter = :pg
+
+  # available options for paginator are: :simple_paginator, :kaminari, :will_paginate
+  # config.paginator = :simple_paginator
 end
 ```
 
 Uncomment the `config.db_adapter` line and set the corresponding value to your
 database and gem. This is all you need.
 
-If you want to make the file from scratch, just copy the above code block into a file inside the `config/initializers` directory.
+Uncomment the `config.paginator` line to set `kaminari or will_paginate` if
+included in your project. It defaults to `simple_paginator`, it falls back to
+passing `offset` and `limit` at the database level (through `ActiveRecord`
+of course).
+
+If you want to make the file from scratch, just copy the above code block into
+a file inside the `config/initializers` directory.
 
 
 #### Using view helpers
 
-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.
+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.
 
 To have these methods available to be used, this is the way to go:
 
@@ -366,7 +512,8 @@ end
 
 #### Options
 
-An `AjaxDatatablesRails::Base` inherited class can accept an options hash at initialization. This provides room for flexibility when required. Example:
+An `AjaxDatatablesRails::Base` inherited class can accept an options hash at
+initialization. This provides room for flexibility when required. Example:
 
 ```ruby
 class UnrespondedMessagesDatatable < AjaxDatatablesRails::Base
@@ -397,7 +544,9 @@ end
 
 #### 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. You can pass a name to your datatable class like this:
+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.
+You can pass a name to your datatable class like this:
 
 
 ```
@@ -412,7 +561,9 @@ $ rails generate datatable UnrespondedMessages
 ```
 
 
-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.
+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.
 
 ## Tutorial
 

data/ajax-datatables-rails.gemspec

@@ -0,0 +1,30 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'ajax-datatables-rails/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "ajax-datatables-rails"
+  gem.version       = AjaxDatatablesRails::VERSION
+  gem.authors       = ["Joel Quenneville"]
+  gem.email         = ["joel.quenneville@collegeplus.org"]
+  gem.description   = %q{A gem that simplifies using datatables and hundreds of records via ajax}
+  gem.summary       = %q{A wrapper around datatable's ajax methods that allow synchronization with server-side pagination in a rails app}
+  gem.homepage      = ""
+  gem.required_ruby_version = Gem::Requirement.new(">= 1.9.3")
+
+  gem.files = Dir["{lib,spec}/**/*", "[A-Z]*"] - ["Gemfile.lock"]
+  gem.executables   = gem.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_path = "lib"
+
+  gem.add_dependency 'railties',   '>= 3.1'
+
+  gem.add_development_dependency "rspec"
+  gem.add_development_dependency "generator_spec"
+  gem.add_development_dependency "pry"
+  gem.add_development_dependency "rake"
+  gem.add_development_dependency "sqlite3"
+  gem.add_development_dependency "rails", ">= 3.1.0"
+  gem.add_development_dependency "activerecord", ">= 4.1.6"
+end

data/lib/ajax-datatables-rails.rb

@@ -1,5 +1,6 @@
 require 'ajax-datatables-rails/version'
 require 'ajax-datatables-rails/config'
+require 'ajax-datatables-rails/models'
 require 'ajax-datatables-rails/base'
 require 'ajax-datatables-rails/extensions/simple_paginator'
 require 'ajax-datatables-rails/extensions/kaminari'

data/lib/ajax-datatables-rails/base.rb

@@ -9,6 +9,7 @@ module AjaxDatatablesRails
     def initialize(view, options = {})
       @view = view
       @options = options
+      load_paginator
     end
 
     def config
@@ -46,6 +47,16 @@ module AjaxDatatablesRails
       }
     end
 
+    def self.deprecated(message, caller = Kernel.caller[1])
+      warning = caller + ": " + message
+
+      if(respond_to?(:logger) && logger.present?)
+        logger.warn(warning)
+      else
+        warn(warning)
+      end
+    end
+
     private
 
     def records
@@ -54,9 +65,9 @@ module AjaxDatatablesRails
 
     def fetch_records
       records = get_raw_records
-      records = sort_records(records)
-      records = filter_records(records)
-      records = paginate_records(records) unless params[:length] == '-1'
+      records = sort_records(records) if params[:order].present?
+      records = filter_records(records) if params[:search].present?
+      records = paginate_records(records) unless params[:length].present? && params[:length] == '-1'
       records
     end
 
@@ -103,6 +114,22 @@ module AjaxDatatablesRails
     end
 
     def search_condition(column, value)
+      if column[0] == column.downcase[0]
+        ::AjaxDatatablesRails::Base.deprecated '[DEPRECATED] Using table_name.column_name notation is deprecated. Please refer to: https://github.com/antillas21/ajax-datatables-rails#searchable-and-sortable-columns-syntax'
+        return deprecated_search_condition(column, value)
+      else
+        return new_search_condition(column, value)
+      end
+    end
+
+    def new_search_condition(column, value)
+      model, column = column.split('.')
+      model = model.constantize
+      casted_column = ::Arel::Nodes::NamedFunction.new('CAST', [model.arel_table[column.to_sym].as(typecast)])
+      casted_column.matches("%#{value}%")
+    end
+
+    def deprecated_search_condition(column, value)
       model, column = column.split('.')
       model = model.singularize.titleize.gsub( / /, '' ).constantize
 
@@ -139,12 +166,48 @@ module AjaxDatatablesRails
     end
 
     def sort_column(item)
-      sortable_columns[item['column'].to_i]
+      new_sort_column(item)
+    rescue
+      ::AjaxDatatablesRails::Base.deprecated '[DEPRECATED] Using table_name.column_name notation is deprecated. Please refer to: https://github.com/antillas21/ajax-datatables-rails#searchable-and-sortable-columns-syntax'
+      deprecated_sort_column(item)
+    end
+
+    def deprecated_sort_column(item)
+      sortable_columns[sortable_displayed_columns.index(item[:column])]
+    end
+
+    def new_sort_column(item)
+      model, column = sortable_columns[sortable_displayed_columns.index(item[:column])].split('.')
+      col = [model.constantize.table_name, column].join('.')
     end
 
     def sort_direction(item)
       options = %w(desc asc)
-      options.include?(item['dir']) ? item['dir'].upcase : 'ASC'
+      options.include?(item[:dir]) ? item[:dir].upcase : 'ASC'
+    end
+
+    def sortable_displayed_columns
+      @sortable_displayed_columns ||= generate_sortable_displayed_columns
+    end
+
+    def generate_sortable_displayed_columns
+      @sortable_displayed_columns = []
+      params[:columns].each_value do |column|
+        @sortable_displayed_columns << column[:data] if column[:orderable] == 'true'
+      end
+      @sortable_displayed_columns
+    end
+
+    def load_paginator
+      case config.paginator
+      when :kaminari
+        extend Extensions::Kaminari
+      when :will_paginate
+        extend Extensions::WillPaginate
+      else
+        extend Extensions::SimplePaginator
+      end
+      self
     end
   end
 end

data/lib/ajax-datatables-rails/config.rb

@@ -20,5 +20,6 @@ module AjaxDatatablesRails
 
     # default db_adapter is pg (postgresql)
     config_accessor(:db_adapter) { :pg }
+    config_accessor(:paginator) { :simple_paginator }
   end
 end

data/lib/ajax-datatables-rails/models.rb

@@ -0,0 +1,6 @@
+require 'active_support/ordered_options'
+
+module AjaxDatatablesRails
+  class Models < ActiveSupport::OrderedOptions
+  end
+end

data/lib/ajax-datatables-rails/version.rb

@@ -1,3 +1,3 @@
 module AjaxDatatablesRails
-  VERSION = '0.2.1'
+  VERSION = '0.3.0'
 end

data/lib/generators/datatable/templates/ajax_datatables_rails_config.rb

@@ -1,4 +1,7 @@
 AjaxDatatablesRails.configure do |config|
   # available options for db_adapter are: :pg, :mysql2, :sqlite3
   # config.db_adapter = :pg
+
+  # available options for paginator are: :simple_paginator, :kaminari, :will_paginate
+  # config.paginator = :simple_paginator
 end

data/lib/generators/rails/templates/datatable.rb

@@ -1,19 +1,12 @@
 class <%= @datatable_name %>Datatable < AjaxDatatablesRails::Base
-  # uncomment the appropriate paginator module,
-  # depending on gems available in your project.
-  # include AjaxDatatablesRails::Extensions::Kaminari
-  # include AjaxDatatablesRails::Extensions::WillPaginate
-  # include AjaxDatatablesRails::Extensions::SimplePaginator
 
   def sortable_columns
-    # list columns inside the Array in string dot notation.
-    # Example: 'users.email'
+    # Declare strings in this format: ModelName.column_name
     @sortable_columns ||= []
   end
 
   def searchable_columns
-    # list columns inside the Array in string dot notation.
-    # Example: 'users.email'
+    # Declare strings in this format: ModelName.column_name
     @searchable_columns ||= []
   end
 

data/spec/ajax-datatables-rails/ajax_datatables_rails_spec.rb

@@ -1,23 +1,6 @@
 require 'spec_helper'
 
 describe AjaxDatatablesRails::Base do
-  class Column
-    def matches(query)
-      []
-    end
-  end
-
-  class User
-    def self.arel_table
-      { :foo => Column.new }
-    end
-  end
-
-  class UserData
-    def self.arel_table
-      { :bar => Column.new }
-    end
-  end
 
   params = {
     :draw => '5',
@@ -95,17 +78,13 @@ describe AjaxDatatablesRails::Base do
     describe '#sort_column' do
       it 'returns a column name from the #sorting_columns array' do
         sort_view = double(
-          'view',
-          :params => {
-            :order => {
-              '0' => { :column => '1' }
-            }
-          }
+          'view', :params => params
         )
         datatable = AjaxDatatablesRails::Base.new(sort_view)
-        datatable.stub(:sortable_columns) { ['foo', 'bar', 'baz'] }
+        allow(datatable).to receive(:sortable_displayed_columns) { ["0", "1"] }
+        allow(datatable).to receive(:sortable_columns) { ['User.foo', 'User.bar', 'User.baz'] }
 
-        expect(datatable.send(:sort_column)).to eq('bar')
+        expect(datatable.send(:sort_column, sort_view.params[:order]["0"])).to eq('users.bar')
       end
     end
 
@@ -120,7 +99,7 @@ describe AjaxDatatablesRails::Base do
           }
         )
         datatable = AjaxDatatablesRails::Base.new(sorting_view)
-        expect(datatable.send(:sort_direction)).to eq('DESC')
+        expect(datatable.send(:sort_direction, sorting_view.params[:order]["0"])).to eq('DESC')
       end
 
       it 'can only be one option from ASC or DESC' do
@@ -133,7 +112,70 @@ describe AjaxDatatablesRails::Base do
           }
         )
         datatable = AjaxDatatablesRails::Base.new(sorting_view)
-        expect(datatable.send(:sort_direction)).to eq('ASC')
+        expect(datatable.send(:sort_direction, sorting_view.params[:order]["0"])).to eq('ASC')
+      end
+    end
+
+    describe "#configure" do
+      let(:datatable) do
+        class FooDatatable < AjaxDatatablesRails::Base
+        end
+
+        FooDatatable.new view
+      end
+
+      context "when model class name is regular" do
+        it "should successfully get right model class" do
+          expect(
+            datatable.send(:search_condition, 'User.bar', 'bar')
+          ).to be_a(Arel::Nodes::Matches)
+        end
+      end
+
+      context "when custom named model class" do
+        it "should successfully get right model class" do
+          expect(
+            datatable.send(:search_condition, 'Statistics::Request.bar', 'bar')
+          ).to be_a(Arel::Nodes::Matches)
+        end
+      end
+
+
+      context "when model class name camelcased" do
+        it "should successfully get right model class" do
+          expect(
+            datatable.send(:search_condition, 'PurchasedOrder.bar', 'bar')
+          ).to be_a(Arel::Nodes::Matches)
+        end
+      end
+
+      context "when model class name is namespaced" do
+        it "should successfully get right model class" do
+          expect(
+            datatable.send(:search_condition, 'Statistics::Session.bar', 'bar')
+          ).to be_a(Arel::Nodes::Matches)
+        end
+      end
+
+      context "when model class defined but not found" do
+        it "raise 'uninitialized constant'" do
+          expect {
+            datatable.send(:search_condition, 'UnexistentModel.bar', 'bar')
+          }.to raise_error(NameError, /uninitialized constant/)
+        end
+      end
+
+      context 'when using deprecated notation' do
+        it 'should successfully get right model class if exists' do
+          expect(
+            datatable.send(:search_condition, 'users.bar', 'bar')
+          ).to be_a(Arel::Nodes::Matches)
+        end
+
+        it 'should display a deprecated message' do
+          expect(AjaxDatatablesRails::Base).to receive(:deprecated)
+          datatable.send(:search_condition, 'users.bar', 'bar')
+        end
       end
     end
 
@@ -156,31 +198,38 @@ describe AjaxDatatablesRails::Base do
     let(:results) { double('Collection', :offset => [], :limit => []) }
     let(:view) { double('view', :params => params) }
     let(:datatable) { AjaxDatatablesRails::Base.new(view) }
+    let(:records) { double('Array').as_null_object }
+
+    before(:each) do
+      allow(datatable).to receive(:sortable_columns) { ['User.foo', 'User.bar'] }
+      allow(datatable).to receive(:sortable_displayed_columns) { ["0", "1"] }
+    end
 
     describe '#paginate_records' do
-      it 'raises a MethodNotImplementedError' do
-        expect { datatable.send(:paginate_records, []) }.to raise_error(
-          AjaxDatatablesRails::Base::MethodNotImplementedError
-        )
+      it 'defaults to Extensions::SimplePaginator#paginate_records' do
+        allow(records).to receive_message_chain(:offset, :limit)
+
+        expect { datatable.send(:paginate_records, records) }.not_to raise_error
       end
     end
 
     describe '#sort_records' do
       it 'calls #order on a collection' do
-        results.should_receive(:order)
+        expect(results).to receive(:order)
         datatable.send(:sort_records, results)
       end
     end
 
     describe '#filter_records' do
-      let(:records) { double('User', :where => []) }
+      let(:records) {  double('User', :where => []) }
       let(:search_view) { double('view', :params => params) }
 
       it 'applies search like functionality on a collection' do
         datatable = AjaxDatatablesRails::Base.new(search_view)
-        datatable.stub(:searchable_columns) { ['users.foo'] }
+        allow(datatable).to receive(:searchable_columns) { ['users.foo'] }
 
-        records.should_receive(:where)
+        expect(records).to receive(:where)
+        records.where
         datatable.send(:filter_records, records)
       end
     end
@@ -191,9 +240,10 @@ describe AjaxDatatablesRails::Base do
 
       it 'applies search like functionality on a collection' do
         datatable = AjaxDatatablesRails::Base.new(search_view)
-        datatable.stub(:searchable_columns) { ['user_datas.bar'] }
+        allow(datatable).to receive(:searchable_columns) { ['user_datas.bar'] }
 
-        records.should_receive(:where)
+        expect(records).to receive(:where)
+        records.where
         datatable.send(:filter_records, records)
       end
     end

data/spec/ajax-datatables-rails/kaminari_spec.rb

@@ -1,10 +1,13 @@
 require 'spec_helper'
 
 class KaminariDatatable < AjaxDatatablesRails::Base
-  include AjaxDatatablesRails::Extensions::Kaminari
 end
 
 describe KaminariDatatable do
+  before(:each) do
+    allow_any_instance_of(AjaxDatatablesRails::Configuration).to receive(:paginator) { :kaminari }
+  end
+
   describe '#paginate_records' do
     let(:users_database) do
       double('User',
@@ -18,15 +21,15 @@ describe KaminariDatatable do
     let(:records) { users_database.all }
 
     it 'calls #page on passed record collection' do
-      records.should_receive(:page)
+      expect(records).to receive(:page)
       datatable.send(:paginate_records, records)
     end
 
     it 'calls #per_page on passed record collection' do
       arry = double('Array', :per => [])
-      records.stub(:page).and_return(arry)
-      arry.should_receive(:per)
+      allow(records).to receive(:page).and_return(arry)
+      expect(arry).to receive(:per)
       datatable.send(:paginate_records, records) 
     end
   end
-end
+end

data/spec/ajax-datatables-rails/models_spec.rb

@@ -0,0 +1,10 @@
+require 'spec_helper'
+
+describe AjaxDatatablesRails::Models do
+  let(:models){ AjaxDatatablesRails::Models.new }
+
+  it "is configurable" do
+    models.user = User
+    expect(models.user).to eq(User)
+  end
+end

data/spec/ajax-datatables-rails/simple_paginator_spec.rb

@@ -18,14 +18,14 @@ describe SimplePaginateDatatable do
     let(:records) { users_database.all }
 
     it 'calls #offset on passed record collection' do
-      records.should_receive(:offset)
+      expect(records).to receive(:offset)
       datatable.send(:paginate_records, records)
     end
 
     it 'calls #limit on passed record collection' do
       arry = double('Array', :limit => [])
-      records.stub(:offset).and_return(arry)
-      arry.should_receive(:limit)
+      allow(records).to receive(:offset).and_return(arry)
+      expect(arry).to receive(:limit)
       datatable.send(:paginate_records, records) 
     end
   end

data/spec/ajax-datatables-rails/will_paginate_spec.rb

@@ -1,10 +1,13 @@
 require 'spec_helper'
 
 class WillPaginateDatatable < AjaxDatatablesRails::Base
-  include AjaxDatatablesRails::Extensions::WillPaginate
 end
 
 describe WillPaginateDatatable do
+  before(:each) do
+    allow_any_instance_of(AjaxDatatablesRails::Configuration).to receive(:paginator) { :will_paginate }
+  end
+
   describe '#paginate_records' do
     let(:users_database) do
       double('User',
@@ -18,8 +21,8 @@ describe WillPaginateDatatable do
     let(:records) { users_database.all }
 
     it 'calls #page and #per_page on passed record collection' do
-      records.should_receive(:paginate).with(:page=>1, :per_page=>10)
+      expect(records).to receive(:paginate).with(:page=>1, :per_page=>10)
       datatable.send(:paginate_records, records)
     end
   end
-end
+end

data/spec/schema.rb

@@ -0,0 +1,35 @@
+ActiveRecord::Schema.define do
+  self.verbose = false
+
+  create_table :users, :force => true do |t|
+    t.string :username
+
+    t.timestamps
+  end
+
+  create_table :user_data, :force => true do |t|
+    t.string :address
+
+    t.timestamps
+  end
+
+  create_table :purchased_orders, :force => true do |t|
+    t.string :foo
+    t.string :bar
+
+    t.timestamps
+  end
+
+  create_table :statistics_requests, :force => true do |t|
+    t.string :baz
+
+    t.timestamps
+  end
+
+  create_table :statistics_sessions, :force => true do |t|
+    t.string :foo
+    t.integer :bar
+
+    t.timestamps
+  end
+end

data/spec/spec_helper.rb

@@ -1,3 +1,9 @@
 require 'pry'
 require 'rails'
+require 'active_record'
 require 'ajax-datatables-rails'
+
+ActiveRecord::Base.establish_connection adapter: "sqlite3", database: ":memory:"
+
+load File.dirname(__FILE__) + '/schema.rb'
+require File.dirname(__FILE__) + '/test_models.rb'

data/spec/test_models.rb

@@ -0,0 +1,21 @@
+class User < ActiveRecord::Base
+end
+
+class UserData < ActiveRecord::Base
+  self.table_name = "user_data"
+end
+
+class PurchasedOrder < ActiveRecord::Base
+end
+
+module Statistics
+  def self.table_name_prefix
+    "statistics_"
+  end
+end
+
+class Statistics::Request < ActiveRecord::Base
+end
+
+class Statistics::Session < ActiveRecord::Base
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: ajax-datatables-rails
 version: !ruby/object:Gem::Version
-  version: 0.2.1
+  version: 0.3.0
 platform: ruby
 authors:
 - Joel Quenneville
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-11-26 00:00:00.000000000 Z
+date: 2015-01-30 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: railties
@@ -80,6 +80,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: rails
   requirement: !ruby/object:Gem::Requirement
@@ -94,6 +108,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: 3.1.0
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.1.6
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 4.1.6
 description: A gem that simplifies using datatables and hundreds of records via ajax
 email:
 - joel.quenneville@collegeplus.org
@@ -106,12 +134,14 @@ files:
 - LICENSE
 - README.md
 - Rakefile
+- ajax-datatables-rails.gemspec
 - lib/ajax-datatables-rails.rb
 - lib/ajax-datatables-rails/base.rb
 - lib/ajax-datatables-rails/config.rb
 - lib/ajax-datatables-rails/extensions/kaminari.rb
 - lib/ajax-datatables-rails/extensions/simple_paginator.rb
 - lib/ajax-datatables-rails/extensions/will_paginate.rb
+- lib/ajax-datatables-rails/models.rb
 - lib/ajax-datatables-rails/version.rb
 - lib/generators/datatable/config_generator.rb
 - lib/generators/datatable/templates/ajax_datatables_rails_config.rb
@@ -119,9 +149,12 @@ files:
 - lib/generators/rails/templates/datatable.rb
 - spec/ajax-datatables-rails/ajax_datatables_rails_spec.rb
 - spec/ajax-datatables-rails/kaminari_spec.rb
+- spec/ajax-datatables-rails/models_spec.rb
 - spec/ajax-datatables-rails/simple_paginator_spec.rb
 - spec/ajax-datatables-rails/will_paginate_spec.rb
+- spec/schema.rb
 - spec/spec_helper.rb
+- spec/test_models.rb
 homepage: ''
 licenses: []
 metadata: {}
@@ -133,7 +166,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: 1.9.2
+      version: 1.9.3
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
@@ -141,7 +174,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
       version: '0'
 requirements: []
 rubyforge_project: 
-rubygems_version: 2.2.2
+rubygems_version: 2.4.5
 signing_key: 
 specification_version: 4
 summary: A wrapper around datatable's ajax methods that allow synchronization with
@@ -149,6 +182,9 @@ summary: A wrapper around datatable's ajax methods that allow synchronization wi
 test_files:
 - spec/ajax-datatables-rails/ajax_datatables_rails_spec.rb
 - spec/ajax-datatables-rails/kaminari_spec.rb
+- spec/ajax-datatables-rails/models_spec.rb
 - spec/ajax-datatables-rails/simple_paginator_spec.rb
 - spec/ajax-datatables-rails/will_paginate_spec.rb
+- spec/schema.rb
 - spec/spec_helper.rb
+- spec/test_models.rb