effective_datatables 2.12.2 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5eed7737db95090d9972bd497d03167274bbcc33
-  data.tar.gz: fc60bd7d87417e5ced94f4d6dbd49256acb49a97
+  metadata.gz: d48516e2bb16d37adae464ea8c9ed86c11310787
+  data.tar.gz: b34bd2c14d20f351a99142c57e8897b16163ca1c
 SHA512:
-  metadata.gz: 8877d69b948273ec1bea41665817a76f12652bacd442fbaa64dfcc4066462d198d96d949aa6b420ede4f52c749c3ddd63230522c6813fa297806d854fe4cd40d
-  data.tar.gz: 33b000a3a093f9cf0f6c08379b924538b34fed19e3cac1aee3b9de9a79cfe54ea6af05ef1fad3b6f7dcf177f435e7ba896eb9f73a7745db715584d113973b0aa
+  metadata.gz: a40f0467539c7a0b08784bc00e54bd4bee2d57e8a86fd0e527b623eaac322a5355670b37004199ac26ac67cb2daa6fa75c30f649f431712bb7a5530221c0aae5
+  data.tar.gz: ff9153ff5e7e69400b1a82f91209c10e672adbe952ac998df2a9c663e73da73f763aa651a09e423307e6e2a4db80f99e83785522ad0f6b7d8272c8319a486169

data/README.md

@@ -1,16 +1,44 @@
 # Effective DataTables
 
-Uniquely powerful server-side searching, sorting and filtering of any ActiveRecord or Array collection as well as post-rendered content displayed as a frontend jQuery Datatable.
+Use a high level DSL and just one ruby file to create a [Datatables jQuery table](http://datatables.net/) for any ActiveRecord class or Array.
 
-Use a simple DSL in just one ruby file to implement all features
+Powerful server-side searching, sorting and filtering of ActiveRecord classes, with `belongs_to` and `has_many` relationships.
 
-Search raw database tables and ruby post-rendered results at the same time
+Does the right thing with searching sql columns as well as computed values from both ActiveRecord and Array collections.
 
-Packages the jQuery DataTables assets for use in a Rails 3.2.x & Rails 4.x application using Twitter Bootstrap 3
+Displays links to associated edit/show/destroy actions based on `current_user` authorized actions.
+
+Other features include aggregate (total/average) footer rows, bulk actions, show/hide columns, responsive collapsing columns and Google charts.
+
+This gem includes the jQuery DataTables assets.
+
+For use with any Rails 3, 4, 5 application already using Twitter Bootstrap 3.
 
 Works with postgres, mysql, sqlite3 and arrays.
 
-## Getting Started
+## effective_datatables 3.0
+
+This is the 3.0 release of effective_datatables.  It's a complete rewrite, with a similar but totally changed DSL.
+
+[Effective Datatables 2.0 README](https://github.com/code-and-effect/effective_datatables/tree/2.12.2)
+
+Previous versions of the gem were excellent, but the 3.0 release has stepped things up.
+
+Internally, all columns now have separate compute and format methods, removing the need for a ton of internal parsing and type conversions.
+This allows things like filters, aggregates and searching/sorting to work effectively.
+
+Column rendering has been improved so all datatable and view methods are callable from anywhere in the DSL.
+This allows the developer to do things like: include/exclude/configure columns based on the current_user, apply logic around current filters
+to change columns dynamically, to use regular ifs instead of procs in toggling visibility, and generally removes all weirdness.
+
+This release adds a dependency on [effective_resources](https://github.com/code-and-effect/effective_resources) for ActiveRecord resource discovery,
+full sql table fuzzy searching/sorting, attribute parsing, and checking availability & authorization of edit/show actions.
+
+A cookie has been added to persist the user's selected filters, search, sort, length, column visibility and pagination settings.
+
+A lot has changed. See below for full details.
+
+# Getting Started
 
 ```ruby
 gem 'effective_datatables'
@@ -42,49 +70,46 @@ Require the stylesheet on the asset pipeline by adding the following to your app
 *= require effective_datatables
 ```
 
-## Usage
+# Quick Start
 
-We create a model, initialize it within our controller, then render it from a view
+All logic for the table exists in its own model file.  Once that's built, we initialize in the controller, render in the view.
 
-### The Model
+## The Model
 
 Start by creating a new datatable.
 
-Below is a very simple example file, which we will expand upon later.
-
 This model exists at `/app/datatables/posts_datatable.rb`:
 
 ```ruby
 class PostsDatatable < Effective::Datatable
   datatable do
-    table_column :id
-    table_column :user      # if Post belongs_to :user
-    table_column :comments  # if Post has_many :comments
-    table_column :title
-    table_column :created_at
-    actions_column
+    col :created_at
+    col :title
+    col :user      # Post belongs_to :user
+    col :comments  # Post has_many :comments
+
+    actions_col
   end
 
-  def collection
+  collection do
     Post.all
   end
-
 end
 ```
 
-### The Controller
+## The Controller
 
-We're going to display this DataTable on the posts#index action
+We're going to display this DataTable on the posts#index action.
 
 ```ruby
 class PostsController < ApplicationController
   def index
-    @datatable = PostsDatatable.new
+    @datatable = PostsDatatable.new(self)
   end
 end
 ```
 
-### The View
+## The View
 
 Here we just render the datatable:
 
@@ -93,778 +118,898 @@ Here we just render the datatable:
 <%= render_datatable(@datatable) %>
 ```
 
-## How It Works
+# Usage
 
-When the jQuery DataTable is first initialized on the front-end, it makes an AJAX request back to the server asking for data.
+Once your controller and view are set up to render a datatable, the model is the central point to configure all behaviour.
 
-The effective_datatables gem intercepts this request and returns the appropriate results.
+Here is an advanced example:
 
-Whenever a search, sort, filter or pagination is initiated on the front end, that request is interpretted by the server and the appropriate results returned.
+## The Model
 
-Due to the unique search/filter ability of this gem, a mix of raw database tables and processed results may be worked with at the same time.
+This model exists at `/app/datatables/posts_datatable.rb`:
 
+```ruby
+class PostsDatatable < Effective::Datatable
 
-### Effective::Datatable Model & DSL
+  # The collection block is the only required section in a datatable
+  # It has access to the attributes and filters Hashes, representing the current state
+  # It must return an ActiveRecord::Relation or an Array of Arrays
+  collection do
+    scope = Post.all.where(created_at: filters[:start_date]...filters[:end_date])
+    scope = scope.where(user_id: attributes[:user_id]) if attributes[:user_id]
+    scope
+  end
 
-Once your controller and view are set up to render a Datatable, the model is the central point to configure all behaviour.
+  # Everything in the filters block ends up in a single form
+  # The form is submitted by datatables javascript as an AJAX post
+  filters do
+    # Scopes are rendered as a single radio button form field (works well with effective_form_inputs gem)
+    # The scopes only work when your collection is an ActiveRecord class, and they must exist on the model
+    # The current scope is automatically applied by effective_datatables to your collection
+    # You don't have to consider the current scope when writing your collection block
+    scope :all, default: true
+    scope :approved
+    scope :draft
+    scope :for_user, (attributes[:user_id] ? User.find(attributes[:user_id]) : current_user)
+
+    # Each filter has a name and a default value and the default can be nil
+    # Each filter is displayed on the front end form as a single field
+    # The filters are NOT automatically applied to your collection
+    # You are responsible for considering filters in your collection block
+    filter :start_date, Time.zone.now-3.months, required: true
+    filter :end_date, Time.zone.now.end_of_day
+  end
 
-This single model file contains just 1 required method and responds to only 3 DSL commands.
+  # These are displayed as a dropdown menu next to the datatables built-in buttons.
+  bulk_actions do
+    # bulk_action is just passthrough to link_to(), but the action of POST is forced
+    # POSTs to the given url with params[:ids], an Array of ids for all selected rows
+    # These actions are assumed to change the underlying collection
+    bulk_action 'Approve all', bulk_approve_posts_path, data: { confirm: 'Approve all selected posts?' }
+    bulk_action_divider
+    bulk_action 'Destroy all', bulk_destroy_posts_path, data: { confirm: 'Destroy all selected posts?' }
+  end
 
-For example: `/app/datatables/posts_datatable.rb`:
+  # Google Charts
+  # https://developers.google.com/chart/interactive/docs/quick_start
+  # effective_datatables does all the javascript boilerplate. Just return an Array of Arrays.
+  # Charts are updated whenever the current filters and search change
+  charts do
+    chart :posts_per_day, 'LineChart', label: 'Posts per Day', legend: false do |collection|
+      collection.group_by { |post| post.created_at.beginning_of_day }.map do |date, posts|
+        [date.strftime('%F'), posts.length]
+      end
+    end
+  end
 
-```ruby
-class PostsDatatable < Effective::Datatable
+  # Datatables
+  # https://datatables.net/
+  # Each column header has a form field controlled by the search: { as: :string } option
+  # The user's selected filters, search, sort, length, column visibility and pagination settings are saved between visits
+  # on a per-table basis and can be Reset with a button
   datatable do
-    default_order :created_at, :desc
-    default_entries 25
+    length 25  # 5, 10, 25, 50, 100, 1000, :all
+    order :updated_at, :desc
 
-    table_column :id, :visible => false
+    # Renders a column of checkboxes to select items for any bulk_actions
+    bulk_actions_col
 
-    table_column :created_at, :width => '25%'
+    col :id, visible: false
+    col :updated_at, visible: false
 
-    table_column :updated_at, :proc => Proc.new { |post| nicetime(post.updated_at) } # just a standard helper as defined in helpers/application_helper.rb
+    col :created_at, label: 'Created' do |post|
+      time_ago_in_words(post.created_at)
+    end
 
-    table_column :user
+    # This is a belongs_to column
+    # effective_datatables will try to put in an edit or show link, depending on the current_user's authorization
+    # It will also initialize the search field with PostCategory.all
+    col :post_category, action: :edit
 
-    table_column :post_category_id, :filter => {:as => :select, :collection => Proc.new { PostCategory.all } } do |post|
-      post.post_category.name.titleize
+    if attributes[:user_id].nil?  # Show all users, otherwise this table is meant for one user only
+      col :user, search: { collection: User.authors }
     end
 
-    array_column :comments do |post|
-      content_tag(:ul) do
-        post.comments.where(:archived => false).map do |comment|
-          content_tag(:li, comment.title)
-        end.join('').html_safe
+    if can?(:index, Comment)
+      col :comments
+    end
+
+    col :category, search: { collection: Post::CATEGORY } do |survey|
+      Post::CATEGORY.invert[post.category]
+    end
+
+    # This is a computed method, not an attribute on the post database table.
+    # The first block takes the object from the collection do ... end block and does some work on it.
+    # It computes some value. A val.
+    # The first block returns a Float/Integer.  All sorting/ordering is then performed on this number.
+    # The second block formats the number and returns a String
+    val :approval_rating do |post|
+      post.approvals.sum { |a| a.rating }
+    end.format do |rating|
+      number_to_percentage(rating, precision: 2)
+    end
+
+    # In a col there is only one block, the format block.
+    # A col takes the value as per the collection do ... end block and just formats it
+    # All sorting/ordering is performed as per the original value.
+    col :approved do |post|
+      if post.approved?
+        content_tag(:span, 'Approved', 'badge badge-approved')
+      else
+        content_tag(:span, 'Draft', 'badge badge-draft')
       end
     end
 
-    table_column :title, :label => 'Post Title', :class => 'col-title'
-    actions_column
-  end
+    # Will add a Total row to the table's tfoot
+    # :average is also supported, or you can do a custom block
+    aggregate :total
 
-  def collection
-    Post.where(:archived => false).includes(:post_category)
+    # Uses effective_resources gem to discover the resource path and authorization actions
+    # Puts in icons to show/edit/destroy actions, if authorized to those actions.
+    # Use the actions_col block to add additional actions
+    actions_col show: false do |post|
+      if !post.approved? && can?(:approve, Post)
+        link_to 'Approve', approve_post_path(post) data: { method: :post, confirm: 'Really approve?'}
+      end
+    end
   end
 
 end
 ```
 
-### The collection
+## The Controller
 
-A required method `def collection` must be defined to return the base ActiveRecord collection.
+Any options used to initialize a datatable become the `attributes`.  Use these to configure datatables behavior.
 
-It can be as simple or as complex as you'd like:
+In the above example, when `attributes[:user_id]` is present, the table displays information for just that user.
 
 ```ruby
-def collection
-  Post.all
+class PostsController < ApplicationController
+  def index
+    @datatable = PostsDatatable.new(self, user_id: current_user.id)
+  end
 end
 ```
 
-or (complex example):
-
-```ruby
-def collection
-  collection = Effective::Order.unscoped.purchased
-    .joins(:user)
-    .joins(:order_items)
-    .group('users.email')
-    .group('orders.id')
-    .select('users.email AS email')
-    .select('orders.*')
-    .select("#{query_total} AS total")
-    .select("string_agg(order_items.title, '!!OI!!') AS order_items")
+## The View
 
-  if attributes[:user_id].present?
-    collection.where(:user_id => attributes[:user_id])
-  else
-    collection
-  end
-end
+Render the datatable with its filters and charts, all together:
 
-def query_total
-  "SUM((order_items.price * order_items.quantity) + (CASE order_items.tax_exempt WHEN true THEN 0 ELSE ((order_items.price * order_items.quantity) * order_items.tax_rate) END))"
-end
+```
+<h1>All Posts</h1>
+<%= render_datatable(@datatable) %>
 ```
 
-### Array Backed collection
+or, the datatable, filter and charts may be rendered individually:
 
-Don't want to use ActiveRecord? Not a problem.
+```
+<h1>All Posts</h1>
+<p>
+  <%= render_datatable_filters(@datatable) %>
+</p>
 
-Define your collection as an Array of Arrays, declare only array_columns, and everything works as expected.
+<p>
+  <%= render_datatable_charts(@datatable) %>
+</p>
 
-```ruby
-class ArrayBackedDatatable < Effective::Datatable
-  datatable do
-    array_column :id
-    array_column :first_name
-    array_column :last_name
-    array_column :email
-  end
+<p>
+<%= render_datatable(@datatable, charts: false, filters: false) %>
+</p>
+```
 
-  def collection
-    [
-      [1, 'June', 'Huang', 'june@einstein.com'],
-      [2, 'Leo', 'Stubbs', 'leo@einstein.com'],
-      [3, 'Quincy', 'Pompey', 'quincy@einstein.com'],
-      [4, 'Annie', 'Wojcik', 'annie@einstein.com'],
-    ]
-  end
+or, to render a simple table, (without filters, charts, pagination, sorting, searching, export buttons, per page, or default visibility):
 
-end
+```
+<%= render_datatable(@datatable, simple: true) %>
 ```
 
-## table_column
+# DSL
 
-This is the main DSL method that you will interact with.
+The effective_datatables DSL is made up of 5 sections: `collection`, `datatable`, `filters` `bulk_actions`, `charts`
 
-table_column defines a 1:1 mapping between a SQL database table column and a frontend jQuery Datatables table column.  It creates a column.
+As well, a datatable can be initialized with `attributes`.
 
-table_column performs searching and sorting on the raw database records, before any results are rendered.
+## attributes
 
-Options may be passed to specify the display, search, sort and filter behaviour for that column.
+When initialized with a Hash, that hash is available throughout the entire datatable as `attributes`.
 
-When the given name of the table_column matches an ActiveRecord attribute, the options are set intelligently based on the underlying datatype.
+These attributes are serialized and stored in an encrypted cookie. Objects won't work. Keep it simple.
+
+Attributes cannot be changed by search, filter, or state in any way. They're guaranteed to be the same as when first initialized.
 
 ```ruby
-# The name of the table column as per the Database
-# This column is detected as an Integer, therefore it is :type => :integer
-# Any SQL used to search this field will take the form of "id = ?"
-table_column :id
+class PostsController < ApplicationController
+  def index
+    @datatable = PostsDatatable.new(self, user_id: current_user.id, admin: true)
+  end
+end
+```
 
-# As per our 'complex' example above, using the .select('customers.stripe_customer_id AS stripe_customer_id') syntax to create a faux database table
-# This column is detected as a String, therefore it is :type => :string
-# Any SQL used to search this field will take the form of "customers.stripe_customer_id ILIKE %?%"
-table_column :stripe_customer_id, :column => 'customers.stripe_customer_id'
+Use attributes to restrict the collection scope, exclude columns or otherwise tweak the table.
 
-# The name of the table column as per the Database
-# This column is detected as a DateTime, therefore it is :type => :datetime
-# Any SQL used to search this field will take the form of
-# "to_char(#{column} AT TIME ZONE 'GMT', 'YYYY-MM-DD HH24:MI') ILIKE '%?%'"
-table_column :created_at
+An example of using `attributes[:user_id]` to make a user specific posts table is above.
 
-# If the name of the table column matches a belongs_to in our collection's main class
-# This column will be detected as a belongs_to and some predefined filters will be set up
-# So declaring the following
-table_column :user
+Here we do something similar with `attributes[:admin]`:
 
-# Will have the same behaviour as declaring
-datatable do
-  if attributes[:user_id].blank?
-    table_column :user_id, :filter => {:as => :select, :collection => Proc.new { User.all.map { |user| [user.id, user.to_s] }.sort { |x, y| x[1] <=> y[1] } } } do |post|
-      post.user.to_s
+```ruby
+class PostsDatatable < Effective::Datatable
+  collection do
+    attributes[:admin] ? Post.all : Post.where(draft: false)
+  end
+
+  datatable do
+    col :title
+
+    if attributes[:admin]
+      col :user
     end
+
+    col :post_category
+    col :comments
   end
 end
 ```
 
-All table_columns are `visible: true`, `sortable: true` by default.
+## collection
 
-## array_column
+The `collection do ... end` block must return an ActiveRecord relation or an Array of Arrays.
 
-`array_column` accepts the same options as `table_column` and behaves identically on the frontend.
+```ruby
+collection do
+  Post.all
+end
+```
 
-The difference occurs with sorting and filtering:
+or
 
-array_columns perform searching and sorting on the computed results after all columns have been rendered.
+```ruby
+collection do
+  scope = Post.includes(:user).where(created_at: filters[:start_date]...filters[:end_date])
+  scope = scope.where(user_id: attributes[:user_id]) if attributes[:user_id]
+  scope
+end
+```
 
-With a `table_column`, the frontend sends some search terms to the server, the raw database table is searched & sorted using standard ActiveRecord .where() and .order(), the appropriate rows returned, and then each row is rendered as per the rendering options.
+or
 
-With an `array_column`, the front end sends some search terms to the server, all rows are returned and rendered, and then the rendered output is searched & sorted.
+```ruby
+collection do
+  [
+    ['June', 'Huang', 'june@einstein.com'],
+    ['Leo', 'Stubbs', 'leo@einstein.com'],
+    ['Quincy', 'Pompey', 'quincy@einstein.com'],
+    ['Annie', 'Wojcik', 'annie@einstein.com'],
+  ]
+end
+```
 
-This allows the output of an `array_column` to be anything complex that cannot be easily computed from the database.
+or
 
-When searching & sorting with a mix of table_columns and array_columns, all the table_columns are processed first so the most work is put on the database, the least on rails.
+```ruby
+collection do
+  time_entries = TimeEntry.where(date: filter[:start_date].beginning_of_year...filter[:end_date].end_of_year)
+    .group_by { |time_entry| "#{time_entry.client_id}_#{time_entry.created_at.strftime('%b').downcase}" }
 
-If you're overriding the `search_column` or `order_column` behaviour of an `array_column`, keep in mind that all values will be strings.
+  Client.all.map do |client|
+    [client] + [:jan, :feb, :mar, :apr, :may, :jun, :jul, :aug, :sep, :oct, :nov, :dec].map do |month|
+      entries = time_entries["#{client.id}_#{month}"] || []
 
-This has the side effect of ordering an `array_column` of numbers, as if they were strings.  To keep them ordered as numbers, call:
+      calc = TimeEntryCalculator.new(entries)
 
-```ruby
-array_column :price, type: :number do |product|
-  number_to_currency(product.price)
+      [calc.duration, calc.bill_duration, calc.overtime, calc.revenue, calc.cost, calc.net]
+    end
+  end
 end
 ```
 
-The above code will output the price as a currency, but still sort the values as numbers rather than as strings.
+The collection block is responsible for applying any `attribute` and `filters` logic.
 
+When an ActiveRecord collection, the `current_scope`, will be applied automatically by effective_datatables.
 
-### General Options
+All searching and ordering is also done by effective_datatables.
 
-The following options control the general behaviour of the column:
+Your collection method should not contain a `.order()`, or implement search in any way.
 
-```ruby
-:column => 'users.id'     # Set this if you're doing something tricky with the database.  Used internally for .order() and .where() clauses
-:type => :string          # Derived from the ActiveRecord attribute default datatype.  Controls searching behaviour.  Valid options include :string, :text, :datetime, :date, :integer, :boolean, :year
-```
+Sometimes it's handy to call `.reorder(nil)` on a scope.
 
-### Display Options
+## datatable
 
-The following options control the display behaviour of the column:
+The `datatable do ... end` block configures a table of data.
 
-```ruby
-:label => 'Nice Label'    # Override the default column header label
-:sortable => true|false   # Allow sorting of this column.  Otherwise the up/down arrows on the frontend will be disabled.
-:visible => true|false    # Hide this column at startup.  Column visbility can be changed on the frontend.  By default, hidden column filter terms are ignored.
-:width => '100%'|'100px'  # Set the width of this column.  Can be set on one, all or some of the columns.  If using percentages, should never add upto more than 100%
-:class => 'col-example'   # Adds an html class to the column's TH and all TD elements.  Add more than one class with 'example col-example something'
-:responsivePriority => 0  # Set which columns collapse when the table is shrunk down.  10000 is the default value.
-```
+Initialize the datatable in your controller or view, `@datatable = PostsDatatable.new(self)`, and render it in your view `<%= render_datatable(@datatable) %>`
 
-### Filtering Options
+### col
 
-Setting a filter will create an appropriate text/number/select input in the header row of the column.
+This is the main DSL method that you will interact with.
 
-The following options control the filtering behaviour of the column:
+`col` defines a 1:1 mapping between the underlying SQL database table column or Array index to a frontend jQuery Datatables table column. It creates a column.
 
-```ruby
-table_column :created_at, :filter => false    # Disable filtering on this column entirely
-table_column :created_at, :filter => {...}    # Enable filtering with these options
+Each column's search and sorting is performed on its underlying value, as per the collection.
 
-:filter => {:as => :number}
-:filter => {:as => :text}
+It accepts one optional block used to format the value after any search or sorting is done.
 
-:filter => {:as => :select, :collection => ['One', 'Two'], :selected => 'Two'}
-:filter => {:as => :select, :collection => [*2010..(Time.zone.now.year+6)]}
-:filter => {:as => :select, :collection => Proc.new { PostCategory.all } }
-:filter => {:as => :select, :collection => Proc.new { User.all.order(:email).map { |obj| [obj.id, obj.email] } } }
+The following options are available:
 
-:filter => {:as => :grouped_select, :collection => {'Active' => Events.active, 'Past' => Events.past }}
-:filter => {:as => :grouped_select, :collection => {'Active' => [['Event A', 1], ['Event B', 2]], 'Past' => [['Event C', 3], ['Event D', 4]]} }
-```
+```ruby
+action: :show|:edit|false  # :resource and relation columns only. generate links to this action. edit -> show by default
+as: :string|:integer|etc   # Sets the type of column initializing defaults for search, sort and format
+col_class: 'col-green'     # Sets the html class to use on this column's td and th
+label: 'My label'          # The label for this column
+partial: 'posts/category'  # Render this column with a partial. The local will be named resource
+partial_as: 'category'     # The name of the object's local variable, otherwise resource
+responsive: 10000          # Controls how columns collapse https://datatables.net/reference/option/columns.responsivePriority
 
-Some additional, lesser used options include:
+# Configure the search behavior. Autodetects by default.
+search: false
+search: :string
+search: { as: :string, fuzzy: true }
+search: { as: :select, collection: User.all, multiple: true }
 
-```ruby
-:filter => {:fuzzy => true} # Will use an ILIKE/includes rather than = when filtering.  Use this for selects.
-:filter => {sql_operation => :having}  # Will use .having() instead of .where() to handle aggregate columns (autodetected)
-:filter => {include_blank: false}
-:filter => {placeholder: false}
+sort: true|false           # Should this column be orderable. true by default
+sql_column: 'posts.rating' # The sql column to search/sort on. Only needed when doing custom selects or tricky joins.
+visible: true|false        # Show/Hide this column by default
 ```
 
-### Rendering Options
+The `:as` setting determines a column's search, sort and format behaviour.
+
+It is auto-detected from an ActiveRecord collection's SQL datatype, and set to `:string` for any Array-based collections.
+
+Valid options for `:as` are as follows:
 
-There are a few different ways to render each column's output.
+`:boolean`, `:currency`, `:datetime`, `:date`, `:decimal`, `:duration`, `:email`, `:float`, `:integer`, `:percentage`, `:price`, `:resource`, `:string`, `:text`
 
-Any standard view helpers like `link_to` or `simple_format` and any custom helpers available to your views will be available.
+These settings are loosely based on the regular datatypes, with some custom effective types thrown in:
 
-All of the following rendering options can be used interchangeably:
+- `:currency` expects the underlying datatype to be a Float.
+- `:duration` expects the underlying datatype to be an Integer representing the number of minutes. 120 == 2 hours
+- `:email` expects the underlying datatype to be a String
+- `:percentage` expects the underlying datatype to be an Integer or a Float. 75 == 0.75 == 75%
+- `:price` expects the underlying datatype to be an Integer representing the number of cents. 5000 == $50.00
+- `:resource` can be used for an Array based collection which includes an ActiveRecord object
 
-Block format (really, this is your cleanest option):
+The column will be formatted as per its `as:` setting, unless a custom format block is present:
 
 ```ruby
-table_column :created_at do |post|
-  if post.created_at > (Time.zone.now-1.year)
-    link_to('this year', post_path(post))
+col :approved do |post|
+  if post.approved?
+    content_tag(:span, 'Approved', 'badge badge-approved')
   else
-    link_to(post.created_at.strftime("%Y-%m-%d %H:%M:%S"), post_path(post))
+    content_tag(:span, 'Draft', 'badge badge-draft')
   end
 end
 ```
 
-Proc format:
+You can also set custom search and sort on a per-column basis. See Advanced Search and Sort below.
 
-```ruby
-table_column :created_at, :proc => Proc.new { |post| link_to(post.created_at, post_path(post)) }
-```
+### val
 
-Partial format:
+Shorthand for value, this command also creates a column on the datatable.
+
+It accepts all the same options as `col` with the additional requirement of a "compute" block.
 
 ```ruby
-table_column :actions, :partial => '/posts/actions'  # render this partial for each row of the table
+val :approval_rating do |post|
+  post.approvals.sum { |a| a.rating }
+end.format do |rating|
+  number_to_percentage(rating, precision: 2)
+end
 ```
 
-then in your `/app/views/posts/_actions.html.erb` file:
+So, `val` yields the object from the collection to the first/compute block, and stores the result.
 
-```erb
-<p><%= link_to('View', post_path(post)) %></p>
-<p><%= link_to('Edit', edit_post_path(post)) %></p>
-```
+All searching and sorting for this column will be performed on this computed value.
 
-The local object name will either match the database table singular name `post`, the name of the partial `actions`, or `obj` unless overridden with:
+This is implemented as a full Array search/sort and is much slower for large datasets than a paginated SQL query
+
+The `.format do ... end` block can then be used to apply custom formatting.
+
+### bulk_actions_col
+
+Creates a column of checkboxes for use with the `bulk_actions` section.
+
+Each input checkbox has a value equal to its row `object.to_param` and gets submitted as an Array of ids, `params[:ids]`
+
+Use these checkboxes to select all / none / one or more rows for the `bulk_actions do ... end` section (below).
+
+You can only have one `bulk_actions_col` per datatable.
+
+### actions_col
+
+When working with an ActiveRecord based collection, this column will consider the `current_user`'s authorization, and generate
+glyphicon links to edit, show and destroy actions for any collection class.
+
+The authorization method is configured via the `config/initializers/effective_datatables.rb` initializer file.
+
+There are just a few options:
 
 ```ruby
-table_column :actions, :partial => '/posts/actions', :partial_local => 'the_post'
+show: true|false|:authorize
+edit: true|false|:authorize
+destroy: true|false|:authorize
+
+visible: true|false
 ```
 
-There are also a built in helper, `datatables_admin_path?` to considering if the current screen is in the `/admin` namespace:
+When the show, edit and destroy actions are `true` (default), the permission check will be made just once, authorizing the class.
+When set to `:authorize`, permission to each individual object will be checked.
+
+Use the block syntax to add additional actions
 
 ```ruby
-table_column :created_at do |post|
-  if datatables_admin_path?
-    link_to admin_posts_path(post)
-  else
-    link_to posts_path(post)
-  end
+actions_col show: false do |post|
+  (post.approved? ? link_to('Approve', approve_post_path(post)) : '') +
+  glyphicon_to('print', print_ticket_path(ticket), title: 'Print')
 end
 ```
 
-The request object is available to the table_column, so you could just as easily call:
+The `glyphicon_to` helper is part of the [effective_resources](https://github.com/code-and-effect/effective_resources) gem, which is a dependency of this gem.
 
-```ruby
-request.referer.include?('/admin/')
-```
+### length
 
-### Column Header Rendering Options
+Sets the default number of rows per page. Valid lengths are `5`, `10`, `25`, `50`, `100`, `250`, `1000`, `:all`
 
-You can override the default rendering and define a partial to use for the header `<th>`:
+When not specified, effective_datatables uses the default as per the `config/initializers/effective_datatables.rb` or 25.
 
 ```ruby
-table_column :special, :header_partial => '/posts/special_header'
+length 100
 ```
 
-The following locals will be available in the header partial:
+### order
+
+Sets the default order of table rows. The first argument is the column, the second the direction.
+
+The column must exist as a `col` or `val` and the direction is either `:asc` or `:desc`.
+
+When not specified, effective_datatables will sort by the first defined column.
 
 ```ruby
-form        # The SimpleForm FormBuilder instance
-name        # The name of your column
-column      # the table_column options
-filterable  # whether the dataTable is filterable
+order :created_at, :asc|:desc
 ```
 
-## actions_column
+### aggregate
+
+The `aggregate` command inserts a row in the table's `tfoot`.
 
-Creates a column with links to this resource's `show`, `edit` and `destroy` actions.
+The only option available is `:label`.
 
-Sets `responsivePriority: 0` so the column is last to collapse when the table is shrunk down.
+You can only have one aggregate per datatable. (Unfortunately, this is a limit of the jQuery Datatables)
 
-Override the default actions by passing your own partial:
+There is built in support for automatic `:total` and `:average` aggregates:
 
 ```ruby
-actions_column partial: 'admin/posts/actions'
+aggregate :total|:average
 ```
 
-or just extend the default by
+or write your own:
 
 ```ruby
-actions_column do |post|
-  unless post.approved?
-    glyphicon_to('ok', approve_post_path(post), title: 'Approve')
+aggregate :average_as_percentage do |values, column|
+  if column[:name] == :first_name
+    'Average'
+  elsif values.present?
+    average = values.map { |value| value.presence || 0 }.sum / [values.length, 1].max
+    content_tag(:span, number_to_percentage(average, precision: 1))
   end
 end
 ```
 
-### Showing action buttons
+In the above example, `values` is an Array containing all row's values for one column at a time.
 
-The show/edit/destroy action buttons can be configured to always show, always hide, or to consider the current_user's permission level.
+## filters
 
-To always show / hide:
+Creates a single form with fields for each `filter` and a single radio input field for all `scopes`.
 
-```ruby
-actions_column show: false, edit: true, destroy: true, unarchive: true
-```
+The form is submitted by an AJAX POST action, or, in some advanced circumstances (see Dynamic Columns below) as a regular POST or even GET.
 
-To authorize based on the current_user and the `config.authorization_method`:
+Initialize the datatable in your controller or view, `@datatable = PostsDatatable.new(self)`, and render its filters anywhere with `<%= render_datatable_filters(@datatable) %>`.
 
-```ruby
-actions_column show: :authorize
-```
+### scope
 
-The above will call the effective_datatables `config.authorization_method` just once to see if the current_user has permission to show/edit/destroy the collection class.
+All defined scopes are rendered as a single radio button form field. Works great with the [effective_form_inputs](https://github.com/code-and-effect/effective_form_inputs) gem.
 
-The action button will be displayed if `EffectiveDatatables.authorized?(controller, :edit, Post)` returns true.
+Only supported for ActiveRecord based collections. They must exist as regular scopes on the model.
 
-To call authorize on each individual resource:
+The currently selected scope will be automatically applied. You shouldn't consider it in your collection block.
 
 ```ruby
-actions_column show: :authorize_each
+filters do
+  scope :approved
+  scope :for_user, current_user
+end
 ```
 
-Or via a Proc:
+Must match the scopes in your `app/models/post.rb`:
 
 ```ruby
-actions_column show: Proc.new { |resource| can?(:show, resource.parent) }
+class Post < ApplicationRecord | ActiveRecord::Base
+  scope :approved, -> { where(draft: false) }
+  scope :for_user, Proc.new { |user| where(user: user) }
+end
 ```
 
-See the `config/initializers/effective_datatable.rb` file for more information.
+### filter
 
-## bulk_actions_column
+Each filter has a name and a default/fallback value. If the form is submitted blank, the default values are used.
 
-Creates a column of checkboxes to select one, some, or all rows and adds a bulk actions dropdown button.
+effective_datatables looks at the default value, and tries to cast the incoming (String) value into that datatype.
 
-When one or more checkboxes are checked, the bulk actions dropdown is enabled and any defined `bulk_action`s will be available to click.
+This ensures that calling `filters[:name]` always return a value. The default can be nil.
 
-Clicking a bulk action makes an AJAX POST request with the parameters `ids: [1, 2, 3]` as per the selected rows.
+You can override the parsing on a per-filter basis.
 
-By default, the method used to determine each row's checkbox value is `to_param`. To call a different method use `bulk_actions_column(resource_method: :slug) do ... end`.
-
-This feature has been built with an ActiveRecord collection in mind. To work with an Array backed collection try `resource_method: :first` or similar.
-
-After the AJAX request is done, the datatable will be redrawn so any changes made to the collection will be displayed immediately.
-
-You can define any number of `bulk_action`s, and separate them with one or more `bulk_action_divider`s.
-
-The `bulk_action` method is just an alias for `link_to`, so all the same options will work.
+Unlike `scope`s, the filters are NOT automatically applied to your collection. You are responsible for considering `filters` in your collection block.
 
 ```ruby
-datatable do
-  bulk_actions_column do
-    bulk_action 'Approve all', bulk_approve_posts_path, data: {confirm: 'Approve all selected posts?'}
-    bulk_action_divider
-    bulk_action 'Send emails', bulk_email_posts_path, data: {confirm: 'Really send emails?'}
-  end
-
-  ...
-
+filters do
+  filter :start_date, Time.zone.now-3.months, required: true
+  filter :end_date, nil, parse: -> { |term| Time.zone.local(term).end_of_day }
+  filter :user, current_user, as: :select, collection: User.all
 end
 ```
 
-You still need to write your own controller action to process the bulk action.  Something like:
+and apply these to your `collection do ... end` block by calling `filters[:start_date]`:
 
 ```ruby
-class PostsController < ApplicationController
-  def bulk_approve
-    @posts = Post.where(id: params[:ids])
+collection do
+  scope = Post.includes(:post_category, :user).where('created_at > ?', filters[:start_date])
 
-    # You should probably write this inside a transaction.  This is just an example.
-    begin
-      @posts.each { |post| post.approve! }
-      render json: { status: 200, message: "Successfully approved #{@posts.length} posts." }
-    rescue => e
-      render json: { status: 500, message: 'An error occured while approving a post.' }
-    end
+  if filters[:end_date].present?
+    scope = scope.where('created_at < ?', filters[:end_date])
   end
+
+  scope
 end
 ```
 
-and in your `routes.rb`:
+The filter command has the following options:
 
 ```ruby
-resources :posts do
-  collection do
-    post :bulk_approve
-  end
-end
+as: :select|:date|:boolean      # Passed to SimpleForm
+label: 'My label'               # Label for this form field
+parse: -> { |term| term.to_i }  # Parse the incoming term (string) into whatever datatype
+required: true|false            # Passed to SimpleForm
 ```
 
-## scopes
+Any other option given will be yielded to SimpleForm as `input_html` options.
 
-When declaring a scope, a form field will automatically be placed above the datatable that can filter on the collection.
+## bulk_actions
 
-The value of the scope, its default value, will be available for use anywehre in your datatable via the `attributes` hash.
+Creates a single dropdown menu with a link to each action, download or content.
 
-```ruby
-scopes do
-  scope :start_date, Time.zone.now-3.months, filter: { input_html: { class: 'datepicker' } }
-end
-```
+Along with this section, you must put a `bulk_actions_col` somewhere in your `datatable do ... end` section.
+
+### bulk_action
+
+Creates a link that becomes clickable when one or more checkbox/rows are selected as per the `bulk_actions_col` column.
 
-(scopes is declared outside of the `datatable do ... end` block)
+A controller action must be created to accept a POST with an array of selected ids, `params[:ids]`.
 
-and then in your collection, or any `table_column` block:
+This is a pass-through to `link_to` and accepts all the same options, except that the method `POST` is forced.
 
 ```ruby
-def collection
-  Post.where('updated_at > ?', attributes[:start_date])
+bulk_actions do
+  bulk_action 'Approve all', bulk_approve_posts_path, data: { confirm: 'Approve all selected posts?' }
 end
 ```
 
-As well, you need to change the controller where you define the datatable to be aware of the scope params.
+In your `routes` file:
 
 ```ruby
-@datatable = PostsDatatable.new(params[:scopes])
+resources :posts do
+  collection do
+    post :bulk_approve
+  end
+end
 ```
 
-And to display the scopes anywhere in your view:
+In your `PostsController`:
 
 ```ruby
-= render_datatable_scopes(@datatable)
+def bulk_approve
+  @posts = Post.where(id: params[:ids])
+
+  # You should probably write this inside a transaction.  This is just an example.
+  begin
+    @posts.each { |post| post.approve! }
+    render json: { status: 200, message: "Successfully approved #{@posts.length} posts." }
+  rescue => e
+    render json: { status: 500, message: 'An error occured while approving a post.' }
+  end
+end
 ```
 
-So initially, the `:start_date` will have the value of `Time.zone.now-3.months` and when submitted by the form, the value will be set there.
+### bulk_action_divider
 
-The form value will come back as a string, so you may need to `Time.zone.parse` that value.
+Inserts a menu divider `<li class='divider' role='separator'></li>`
 
-Pass `scope :start_date, Time.zone.now-3.months, fallback: true` to fallback to the default value when the form submission is not present.
+### bulk_download
 
-Any `filter: { ... }` options will be passed straight into simple_form.
+So it turns out there are some http issues with using an AJAX action to download a file.
 
-### current_scope / model scopes
+A workaround for these issues is included via the [jQuery File Download Plugin](http://johnculviner.com/jquery-file-download-plugin-for-ajax-like-feature-rich-file-downloads/)
 
-You can also use scopes as defined on your ActiveRecord model
-
-When a scope is passed like follows, without a default value, it is assumed to be a klass level scope:
+The use case for this feature is to download a csv report generated for the selected rows.
 
 ```ruby
-scopes do
-  scope :all
-  scope :standard, default: true
-  scope :extended
-  scope :archived
-end
-
-def collection
-  collection = Post.all
-  collection = collection.send(current_scope) if current_scope
-  collection
+bulk_actions do
+  bulk_download 'Export Report', bulk_export_report_path
 end
 ```
 
-The front end will render these klass scopes as a radio buttons / button group.
+```ruby
+def bulk_export_report
+  authorize! :export, Post
+
+  @posts = Post.where(id: params[:ids])
 
-To determine which scope is selected, you can call `current_scope` or `attributes[:current_scope]` or `attributes[:standard]`
+  Post.transaction do
+    begin
+      cookies[:fileDownload] = true
 
-When no scopes are selected, and no defaults are present, the above will return nil.
+      send_data(PostsExporter.new(@posts).export,
+        type: 'text/csv; charset=utf-8; header=present',
+        filename: 'posts-export.csv'
+      )
 
-It's a bit confusing, but you can mix and match these with regular attribute scopes.
+      @posts.update_all(exported_at: Time.zone.now)
+      return
+    rescue => e
+      cookies.delete(:fileDownload)
+      raise ActiveRecord::Rollback
+    end
+  end
 
-## aggregates
+  render json: { error: 'An error occurred' }
+end
+```
 
-Each `aggregate` directive adds an additional row to the table's tfoot.
+### bulk_action_content
 
-This feature is intended to display a sum or average of all the table's currently displayed values.
+Blindly inserts content into the dropdown.
 
 ```ruby
-aggregate :average do |table_column, values, table_data|
-  if table_column[:name] == 'user'
-    'Average'
-  else
-    average = (values.sum { |value| convert_to_column_type(table_column, value) } / [values.length, 1].max)
-    content_tag(:span, number_to_percentage(average, precision: 0))
+bulk_actions do
+  bulk_action_content do
+    content_tag(:li, 'Something')
   end
 end
 ```
 
-The above aggregate block will be called for each currently visible column in a datatable.
-
-Here `table_column` is the table_column being rendered, `values` is an array of all the values in this one column. `table_data` is the whole transposed array of data.
-
-The values will be whatever datatype each table_column returns.
+Don't actually use this.
 
-It might be the case that the formatted values (strings) are returned, which is why `convert_to_column_type` is used above.
+## charts
 
-## table_columns
+Create a [Google Chart](https://developers.google.com/chart/interactive/docs/quick_start) based on your searched collection, filters and attributes.
 
-Quickly create multiple table_columns all with default options:
+No javascript required. Just use the `chart do ... end` block and return an Array of Arrays.
 
 ```ruby
-table_columns :id, :created_at, :updated_at, :category, :title
-```
-
-## default_order
-
-Sort the table by this field and direction on start up
+charts do
+  chart :breakfast, 'BarChart' do |collection|
+    [
+      ['Bacon', 10],
+      ['Eggs', 20],
+      ['Toast', 30]
+    ]
+  end
 
-```ruby
-default_order :created_at, :asc|:desc
+  chart :posts_per_day, 'LineChart', label: 'Posts per Day', legend: false do |collection|
+    collection.group_by { |post| post.created_at.beginning_of_day }.map do |date, posts|
+      [date.strftime('%F'), posts.length]
+    end
+  end
+end
 ```
 
-## default_entries
-
-The number of entries to show per page
+And then render each chart in your view:
 
-```ruby
-default_entries :all
+```
+<%= render_datatable_chart(@datatable, :breakfast) %>
+<%= render_datatable_chart(@datatable, :posts_per_day) %>
 ```
 
-Valid options are `10, 25, 50, 100, 250, 1000, :all`
+or all together
 
-## Additional Functionality
+```
+<%= render_datatable_charts(@datatable) %>
+```
 
-There are a few other ways to customize the behaviour of effective_datatables
+All options passed to `chart` are used to initialize the chart javascript.
 
-### Checking for Empty collection
+By default, the only package that is loaded is `corechart`, see the `config/initializers/effective_datatables.rb` file to add more packages.
 
-Check whether the datatable has records by calling `@datatable.empty?` and `@datatable.present?`.
+## Extras
 
-Keep in mind, these methods look at the collection's total records, not the currently displayed/filtered records.
+The following commands don't quite fit into the DSL, but are present nonetheless.
 
-### Hide the buttons
+### simple
 
-To hide the Bulk Actions, Show / Hide Columns, CSV, Excel, Print, etc buttons:
+To render a simple table, without pagination, sorting, filtering, export buttons, per page, and default visibility:
 
-```ruby
-render_datatable(@datatable, buttons: false)
+```
+<%= render_datatable(@datatable, simple: true) %>
 ```
 
-### Override javascript options
+### index
 
-The javascript options used to initialize a datatable can be overriden as follows:
+If you just want to render a datatable and nothing else, there is a quick way to skip creating a view:
 
 ```ruby
-render_datatable(@datatable, {dom: "<'row'<'col-sm-12'tr>>", autoWidth: true})
+class PostsController < ApplicationController
+  def index
+    render_datatable_index PostsDatatable.new(self)
+  end
+end
 ```
 
-Please see [datatables options](https://datatables.net/reference/option/) for a list of initialization options.
-
-
-### Customize Filter Behaviour
+will render `views/effective/datatables/index` with the assigned datatable.
 
-This gem does its best to provide "just works" filtering of both raw SQL (table_column) and processed results (array_column) out-of-the-box.
+## Advanced Search and Sort
 
-It's also very easy to override the filter behaviour on a per-column basis.
+The built-in search and ordering can be overridden on a per-column basis.
 
-Keep in mind, that filter terms applied to hidden columns will still be considered in filter results.
+The only gotcha here is that you must be aware of the type of collection.
 
-To customize filter behaviour, specify a `def search_column` method in the datatables model file.
-
-If the table column being customized is a table_column:
+In the case of a `col` and an ActiveRecord-based collection:
 
 ```ruby
-def search_column(collection, table_column, search_term, sql_column)
-  if table_column[:name] == 'subscription_types'
-    collection.where('subscriptions.stripe_plan_id ILIKE ?', "%#{search_term}%")
-  else
-    super
+collection do
+  Post.all
+end
+
+datatable do
+  col :post_category do |post|
+    content_tag(:span, post.post_category, "badge-#{post.post_category}")
+  end.search do |collection, term, column, sql_column|
+    # collection is an ActiveRecord scoped collection
+    # term is the incoming PostCategory ID as per the search
+    # column is this column's attributes Hash
+    # sql_column is the column[:sql_column]
+    categories = current_user.post_categories.where(id: term.to_i)
+
+    collection.where(post_category_id: categories)  # Must return an ActiveRecord scope
+  end.sort do |collection, direction, column, sql_column|
+    collection.joins(:post_category).order(:post_category => :title, direction)
   end
 end
 ```
 
-And if the table column being customized is an array_column:
+And in the case of a `col` with an Array-based collection, or any `val`:
 
 ```ruby
-def search_column(collection, table_column, search_term, index)
-  if table_column[:name] == 'price'
-    collection.select! { |row| row[index].include?(search_term) }
-  else
-    super
+collection do
+  Client.all.map do |client|
+    [client, client.first_name client.last_name, client.purchased_time()]
+  end
+end
+
+datatable do
+  col :client
+  col :first_name
+  col :last_name
+
+  col :purchased_time do |duration|
+    number_to_duration(duration)
+  end.search do |collection, term, column, index|
+    # collection is an Array of Arrays
+    # term is the incoming value as per the search. "3h30m"
+    # column is the column's attributes Hash
+    # index is this column's index in the collection
+    (hours, minutes) = term.to_s.gsub(/[^0-9|h]/, '').split.map(&:to_i)
+    duration = (hours.to_i * 60) + minutes.to_i
+
+    collection.select! { |row| row[index] == duration }  # Must return an Array of Arrays
+  end.sort do |collection, term, column, index|
+    collection.sort! do |x, y|
+      x[index] <=> y[index]
+    end
   end
 end
 ```
 
-### Customize Order Behaviour
+The search and sort for each column will be merged together to form the final results.
 
-The order behaviour can be overridden on a per-column basis.
+### Default search collection
 
-To custom order behaviour, specify a `def order_column` method in the datatables model file.
+When using a `col :user` type belongs_to or has_many column, a search collection for that class will be loaded.
 
-If the table column being customized is a table_column:
+Add the following to your related model to customize the search collection:
 
 ```ruby
-def order_column(collection, table_column, direction, sql_column)
-  if table_column[:name] == 'subscription_types'
-    sql_direction = (direction == :desc ? 'DESC' : 'ASC')
-    collection.joins(:subscriptions).order("subscriptions.stripe_plan_id #{sql_direction}")
-  else
-    super
-  end
+class Comment < ApplicationRecord
+  scope :datatables_filter, -> { Comment.includes(:user) }
 end
 ```
 
-And if the table column being customized is an array_column:
+Datatables will look for a `datatables_filter` scope, or `sorted` scope, or fallback to `all`.
 
-```ruby
-def order_column(collection, table_column, direction, index)
-  if table_column[:name] == 'price'
-    if direction == :asc
-      collection.sort! { |a, b| a[index].gsub(/\D/, '').to_i <=> b[index].gsub(/\D/, '').to_i }
-    else
-      collection.sort! { |a, b| b[index].gsub(/\D/, '').to_i <=> a[index].gsub(/\D/, '').to_i }
-    end
-  else
-    super
-  end
-end
-```
-
-### Initialize with attributes
+If there are more than 500 max records, the filter will fallback to a `as: :string`.
 
-Any attributes passed to `.new()` will be persisted through the lifecycle of the datatable.
+## Dynamic Column Count
 
-You can use this to scope the datatable collection or create even more advanced search behaviour.
+There are some extra steps to be taken if you want to change the number of columns based on `filters`.
 
-In the following example we will hide the User column and scope the collection to a specific user.
+Unfortunately, the DataTables jQuery doesn't support changing columns, so submitting filters needs to be done via POST instead of AJAX.
 
-In your controller:
+The following example displays a client column, and one column per month for each month in a date range:
 
 ```ruby
-class PostsController < ApplicationController
-  def index
-    @datatable = PostsDatatable.new(:user_id => current_user.try(:id))
-  end
-end
-```
+class TimeEntriesPerClientReport < Effective::Datatable
 
-And then in your datatable:
+  filters do
+    # This instructs the filters form to use a POST, if available, or GET instead of AJAX
+    # It posts to the current controller/action, and there are no needed changes in your controller
+    changes_columns_count
 
-```ruby
-class PostsDatatable < Effective::Datatable
-  datatable do
-    if attributes[:user_id].blank?
-      table_column :user_id { |post| post.user.email }
-    end
+    filter :start_date, (Time.zone.now - 6.months).beginning_of_month, required: true, label: 'For the month of: ', as: :effective_date_picker
+    filter :end_date, Time.zone.now.end_of_month, required: true, label: 'upto and including the whole month of', as: :effective_date_picker
   end
 
-  def collection
-    if attributes[:user_id]
-      Post.where(user_id: attributes[:user_id])
-    else
-      Post.all
+  datatable do
+    length :all
+
+    col :client
+
+    selected_months.each do |month|
+      col month.strftime('%b %Y'), as: :duration
     end
+
+    actions_col
   end
-end
-```
 
-### Helper methods
+  collection do
+    time_entries = TimeEntry.where(date: filter[:start_date].beginning_of_month...filter[:end_date].end_of_month)
+      .group_by { |time_entry| "#{time_entry.client_id}_#{time_entry.created_at.strftime('%b')}" }
 
-Any non-private methods defined in the datatable model will be available to your table_columns and evaluated in the view_context.
+    Client.all.map do |client|
+      [client] + selected_months.map do |month|
+        entries = time_entries["#{client.id}_#{month.strftime('%b')}"] || []
 
-```ruby
-class PostsDatatable < Effective::Datatable
-  def format_post_title(post)
-    if post.title.start_with?('important')
-      link_to(post.title.upcase, post_path(post))
-    else
-      link_to(post.title, post_path(post))
+        entries.map { |entry| entry.duration }.sum
+      end
     end
   end
 
-  datatable do
-    table_column :title do |post|
-      format_post_title(post)
+  # Returns an array of 2016-Jan-01, 2016-Feb-01 datetimes
+  def selected_months
+    @selected_months ||= [].tap do |months|
+      each_month_between(filter[:start_date].beginning_of_month, filter[:end_date].end_of_month) { |month| months << month }
     end
   end
 
-  def collection
-    Post.all
+  # Call with each_month_between(start_date, end_date) { |date| puts date }
+  def each_month_between(start_date, end_date, &block)
+    while start_date <= end_date
+      block.call(start_date)
+      start_date = start_date + 1.month
+    end
   end
 end
 ```
 
-You can also get the same functionality by including a regular Rails helper within the datatable model.
+# Additional Functionality
 
-```ruby
-module PostHelper
-end
-```
-
-```ruby
-class PostsDatatable < Effective::Datatable
-  include PostsHelper
-end
-```
-
-## Working with other effective_gems
-
-### Effective Addresses
-
-When working with an ActiveRecord collection that implements [effective_addresses](https://github.com/code-and-effect/effective_addresses),
-the filters and sorting will be automatically configured.
-
-Just define `table_column :addresses`
-
-When filtering values in this column, the address1, address2, city, postal code, state code and country code will all be matched.
-
-### Effective Obfuscation
-
-When working with an ActiveRecord collection that implements [effective_obfuscation](https://github.com/code-and-effect/effective_obfuscation) for the ID column,
-that column's filters and sorting will be automatically configured.
+There are a few other ways to customize the behaviour of effective_datatables
 
-Just define `table_column :id`
+## Checking for Empty collection
 
-Unfortunately, due to the effective_obfuscation algorithm, sorting and filtering by partial values is not supported.
+Check whether the datatable has records by calling `@datatable.empty?` and `@datatable.present?`.
 
-So the column may not be sorted, and may only be filtered by typing the entire 10-digit number, with or without any formatting.
+## Override javascript options
 
-### Effective Roles
+The javascript options used to initialize a datatable can be overriden as follows:
 
-When working with an ActiveRecord collection that implements [effective_roles](https://github.com/code-and-effect/effective_roles),
-the filters and sorting will be automatically configured.
+```ruby
+render_datatable(@datatable, input_js: { dom: "<'row'<'col-sm-12'tr>>", autoWidth: true })
+```
 
-Just define `table_column :roles`
+```ruby
+render_datatable(@datatable, input_js: { buttons_export_columns: ':visible:not(.col-actions)' })
+```
 
-The `EffectiveRoles.roles` collection will be used for the filter collection, and sorting will be done by roles_mask.
+Please see [datatables options](https://datatables.net/reference/option/) for a list of initialization options.
 
+You don't want to actually do this!
 
 ## Get access to the raw results
 
@@ -886,20 +1031,6 @@ def finalize(collection)
 end
 ```
 
-## Customize the datatables JS initializer
-
-You can customize the initializer javascript passed to datatables.
-
-The support for this is still pretty limitted.
-
-```
-= render_datatable(@datatable, {colReorder: false})
-```
-
-```
-= render_datatable(@datatable, { buttons_export_columns: ':visible:not(.col-actions)' })
-```
-
 ## Authorization
 
 All authorization checks are handled via the config.authorization_method found in the `config/initializers/effective_datatables.rb` file.
@@ -961,17 +1092,6 @@ end
 
 MIT License.  Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
 
-
-## Testing
-
-The test suite for this gem is unfortunately not yet complete.
-
-Run tests by:
-
-```ruby
-rake spec
-```
-
 ## Contributing
 
 1. Fork it