Merge branch 'base'

Conflicts:
	CHANGELOG.md
	Rakefile
	ajax-datatables-rails.gemspec
	lib/ajax-datatables-rails.rb
	lib/generators/ajaxdatatable/templates/datatable.rb
	spec/ajax-datatables-rails/ajax_datatables_rails_spec.rb
	spec/spec_helper.rb

Author: antillas21

CHANGELOG.md

@@ -2,4 +2,10 @@
 
 ## 0.1.0
 * A fresh start. Changes base class name to: `DatatablesRails`.
-* 
+* Extracts pagination functions to mixable modules.
+  * A user would have the option to stick to the base
+    `DatatablesRails::Extensions::SimplePaginator` or replace it with
+    `DatatablesRails::Extensions::Kaminari` or
+    `DatatablesRails::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.
+* Datatable constructor accepts an optional `options` hash to provide more flexibility. See [README](https://github.com/antillas21/ajax-datatables-rails/blob/master/README.md) for examples.

README.md

@@ -13,59 +13,83 @@ Datatables is a nifty jquery plugin that adds the ability to paginate, sort, and
 
 `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.
 
+## ORM Support
+
+Currently, it only supports `ActiveRecord` as ORM for performing database queries.
+
 ## Installation
 
 Add these lines to your application's Gemfile:
 
     gem 'jquery-datatables-rails'
-    gem 'ajax-datatables-rails'
+    gem 'rails-datatables'
 
 And then execute:
 
     $ bundle
 
 ## Usage
+*The following examples assume that we are setting up rails-datatables for an index of users from a `User` model*
 
-*The following examples assume that we are setting up ajax-datatables-rails for an index of users from a `User` model*
-
-### Model
+### Generate
 Run the following command:
 
-    $ rails generate ajaxdatatable User
+    $ rails generate datatable User
 
-This will generate a file named `users_datatable.rb` in `app/datatables`. Open the file and customize in the functions as directed by the comments
 
-#### Initializer
+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
+
+### Customize
 ```ruby
-def initialize(view)
-  @model_name = User
-  @columns = # insert array of column names here
-  @searchable_columns = #insert array of columns that will be searched
-  super(view)
+# 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'
+  @sortable_columns ||= []
+end
+
+def searchable_columns
+  # list columns inside the Array in string dot notation.
+  # Example: 'users.email'
+  @searchable_columns ||= []
 end
 ```
 
-* For `@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 `extensions`, 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` falls back to passing `offset` and `limit` at the database level (through `ActiveRecord` of course).
+
+* 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. For example `[users.f_name, users.l_name]`
 
 This gives us:
 ```ruby
-def initialize(view)
-  @model_name = User
-  @columns = [users.f_name, users.l_name, users.bio]
-  @searchable_columns = [users.f_name, users.l_name]
-  super(view)
+include AjaxDatatablesRails::Extensions::Kaminari
+
+def sortable_columns
+  @sortable_columns ||= ['users.f_name', 'users.l_name', 'users.bio']
 end
+
+def searchable_columns
+  @searchable_columns ||= ['users.f_name', 'users.l_name']
+end
+
 ```
 
-#### Data
+### Map data
 ```ruby
 def data
-  users.map do |user|
+  records.map do |record|
     [
-      # comma separated list of the values for each cell of a table row
-    ]
+        # comma separated list of the values for each cell of a table row
+        # example: record.attribute,
+      ]
   end
 end
 ```
@@ -74,11 +98,11 @@ This method builds a 2d array that is used by datatables to construct the html t
 
 ```ruby
 def data
-  users.map do |user|
+  records.map do |record|
     [
-      user.f_name,
-      user.l_name,
-      user.bio
+      record.f_name,
+      record.l_name,
+      record.bio
     ]
   end
 end
@@ -106,7 +130,7 @@ Set up the controller to respond to JSON
 def index
   respond_to do |format|
     format.html
-    format.json { render json: UsersDatatable.new(view_context) }
+    format.json { render json: UserDatatable.new(view_context) }
   end
 end
 ```
@@ -138,17 +162,55 @@ Finally, the javascript to tie this all together. In the appropriate `js.coffee`
 
 ```coffeescript
 $ ->
-  $('#users-table').dataTable
+  $('#user-table').dataTable
     bProcessing: true
     bServerSide: true
-    sAjaxSource: $('#users-table').data('source')
+    sAjaxSource: $('#user-table').data('source')
 ```
 
+### Additional Notes
+
+#### Options
+
+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
+  # customized methods here
+end
+
+datatable = UnrespondedMessagesDatatable.new(
+  view_context, { :foo => { :bar => Baz.new }, :from => 1.month.ago }
+)
+
+datatable.options
+#=> { :foo => { :bar => #<Baz:0x007fe9cb4e0220> }, :from => 2014-04-16 19:55:28 -0700 }
+```
+
+#### 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:
+
+
+```
+$ rails generate datatable users
+# returns a users_datatable.rb file with a UsersDatatable class
+
+$ rails generate datatable contact_messages
+# returns a contact_messages_datatable.rb file with a ContactMessagesDatatable class
+
+$ rails generate datatable UnrespondedMessages
+# returns an unresponded_messages_datatable.rb file with an UnrespondedMessagesDatatable class
+```
+
+
+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.
+
+
 ## Contributing
 
 1. Fork it
 2. Create your feature branch (`git checkout -b my-new-feature`)
 3. Commit your changes (`git commit -am 'Added some feature'`)
 4. Push to the branch (`git push origin my-new-feature`)
 5. Create new Pull Request
-

Rakefile

@@ -8,7 +8,7 @@ task :default => :spec
 task :console do
   require 'pry'
   require 'rails'
-  require 'ajax_datatables_rails'
+  require 'ajax-datatables-rails'
   ARGV.clear
   Pry.start
-end
+end

ajax-datatables-rails.gemspec

@@ -1,11 +1,11 @@
 # -*- encoding: utf-8 -*-
 lib = File.expand_path('../lib', __FILE__)
 $LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
-require 'ajax_datatables_rails/version'
+require 'ajax-datatables-rails/version'
 
 Gem::Specification.new do |gem|
   gem.name          = "ajax-datatables-rails"
-  gem.version       = DatatablesRails::VERSION
+  gem.version       = AjaxDatatablesRails::VERSION
   gem.authors       = ["Joel Quenneville"]
   gem.email         = ["[email protected]"]
   gem.description   = %q{A gem that simplifies using datatables and hundreds of records via ajax}

lib/ajax-datatables-rails.rb

@@ -0,0 +1,8 @@
+require 'ajax-datatables-rails/version'
+require 'ajax-datatables-rails/base'
+require 'ajax-datatables-rails/extensions/simple_paginator'
+require 'ajax-datatables-rails/extensions/kaminari'
+require 'ajax-datatables-rails/extensions/will_paginate'
+
+module AjaxDatatablesRails
+end

lib/ajax-datatables-rails/base.rb

@@ -0,0 +1,128 @@
+module AjaxDatatablesRails
+  class Base
+    extend Forwardable
+    class MethodNotImplementedError < StandardError; end
+
+    attr_reader :view, :options, :sortable_columns, :searchable_columns
+    def_delegator :@view, :params, :params
+
+    def initialize(view, options = {})
+      @view = view
+      @options = options
+    end
+
+    def sortable_columns
+      @sortable_columns ||= []
+    end
+
+    def searchable_columns
+      @searchable_columns ||= []
+    end
+
+    def data
+      fail(
+        MethodNotImplementedError,
+        'Please implement this method in your class.'
+      )
+    end
+
+    def get_raw_records
+      fail(
+        MethodNotImplementedError,
+        'Please implement this method in your class.'
+      )
+    end
+
+    def as_json(options = {})
+      {
+        :sEcho => params[:sEcho].to_i,
+        :iTotalRecords => get_raw_records.count,
+        :iTotalDisplayRecords => filter_records(get_raw_records).count,
+        :aaData => data
+      }
+    end
+
+    private
+
+    def records
+      @records ||= fetch_records
+    end
+
+    def fetch_records
+      records = get_raw_records
+      records = sort_records(records)
+      records = filter_records(records)
+      records = paginate_records(records)
+      records
+    end
+
+    def sort_records(records)
+      records.order("#{sort_column} #{sort_direction}")
+    end
+
+    def paginate_records(records)
+      fail(
+        MethodNotImplementedError,
+        'Please mixin a pagination extension.'
+      )
+    end
+
+    def filter_records(records)
+      records = simple_search(records)
+      records = composite_search(records)
+      records
+    end
+
+    def simple_search(records)
+      return records unless params[:sSearch]
+      conditions = build_conditions_for(params[:sSearch])
+      records = records.where(conditions) if conditions
+      records
+    end
+
+    def composite_search(records)
+      conditions = aggregate_query
+      records = records.where(conditions) if conditions
+      records
+    end
+
+    def build_conditions_for(query)
+      searchable_columns.map { |col| search_condition(col, query) }.reduce(:or)
+    end
+
+    def search_condition(column, value)
+      model, column = column.split('.')
+      model = model.singularize.titleize.constantize
+      model.arel_table[column.to_sym].matches("%#{value}%")
+    end
+
+    def aggregate_query
+      conditions = searchable_columns.each_with_index.map do |column, index|
+        value = params["sSearch_#{index}".to_sym]
+        search_condition(column, value) if value
+      end
+      conditions.compact.reduce(:and)
+    end
+
+    def offset
+      (page - 1) * per_page
+    end
+
+    def page
+      (params[:iDisplayStart].to_i / per_page) + 1
+    end
+
+    def per_page
+      params.fetch(:iDisplayLength, 10).to_i
+    end
+
+    def sort_column
+      sortable_columns[params[:iSortCol_0].to_i]
+    end
+
+    def sort_direction
+      options = %w(desc asc)
+      options.include?(params[:sSortDir_0]) ? params[:sSortDir_0].upcase : 'ASC'
+    end
+  end
+end

lib/ajax-datatables-rails/extensions/kaminari.rb

@@ -0,0 +1,12 @@
+module AjaxDatatablesRails
+  module Extensions
+    module Kaminari
+
+      private
+      
+      def paginate_records(records)
+        records.page(page).per(per_page)
+      end
+    end
+  end
+end

lib/ajax-datatables-rails/extensions/simple_paginator.rb

@@ -0,0 +1,12 @@
+module AjaxDatatablesRails
+  module Extensions
+    module SimplePaginator
+
+      private
+      
+      def paginate_records(records)
+        records.offset(offset).limit(per_page)
+      end
+    end
+  end
+end