ajax-datatables-rails 0.4.3 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 32f4790c082cfaf7a15b4463d51e7bfd1d16ddb215ad132a40572765ff79e262
-  data.tar.gz: cca488fce38bd4ea5dcba5112dca37fbc106c196010362ad1b2c24d231d0cf72
+  metadata.gz: 48269680add42469ca399b87c62e395e7496c576ff1e5e350c67156d2b9daf6e
+  data.tar.gz: 2f1798f22e4cbe46709b54ec31a589c00a076e0a989b67d8aa76f7a550e9531f
 SHA512:
-  metadata.gz: 3f50889d4584929e3a01f8895d7b3e10e8118dcfa7fe2a4188eefe38f2cdc4b3bf0b043f996a7c7d43ba7706f085dd3dddab84756f8e21d74e3f55f1a73ab083
-  data.tar.gz: 7b36341f278d8cf407cd21060635b37723c14f7b564e510bf5699e6665d81b8fd282220d5fe031ad97f8b67224ce3ab0dddd4131ff18287ff3576d34df1af74d
+  metadata.gz: 1821dac17ccb0ecc2e5b81ceffd2e3401a7ebe004e388378ab118046bafcf9634dbcb2dbb28a18a1e7482d21abfd28cf0e3868265a1ed88f0b648e81a701a6e9
+  data.tar.gz: d6ed01a390d8f9c16861d7258a57e65ac40ce5b1fd8bd74f43185e8ad27009393017d64bd33e43e2c649ee59394abc41591a74dff4767d56ddba61435f10de7f

data/.rubocop.yml

@@ -1,6 +1,7 @@
 AllCops:
   TargetRubyVersion: 2.5
   Exclude:
+    - gemfiles/*
     - spec/**/*.rb
     - lib/ajax-datatables-rails.rb
     - lib/generators/rails/templates/*.rb

data/.travis.yml

@@ -3,53 +3,14 @@ language: ruby
 sudo: required
 cache: bundler
 rvm:
-  - 2.2.10
   - 2.3.7
+  - 2.4.4
+  - 2.5.1
 gemfile:
-  - gemfiles/rails_4.0.13.gemfile
-  - gemfiles/rails_4.1.16.gemfile
   - gemfiles/rails_4.2.10.gemfile
   - gemfiles/rails_5.0.7.gemfile
   - gemfiles/rails_5.1.6.gemfile
   - gemfiles/rails_5.2.0.gemfile
-matrix:
-  include:
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_4.2.10.gemfile
-      env: DB_ADAPTER=postgresql
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.0.7.gemfile
-      env: DB_ADAPTER=postgresql
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.1.6.gemfile
-      env: DB_ADAPTER=postgresql
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.2.0.gemfile
-      env: DB_ADAPTER=postgresql
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_4.2.10.gemfile
-      env: DB_ADAPTER=mysql2
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.0.7.gemfile
-      env: DB_ADAPTER=mysql2
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.1.6.gemfile
-      env: DB_ADAPTER=mysql2
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.2.0.gemfile
-      env: DB_ADAPTER=mysql2
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_4.2.10.gemfile
-      env: DB_ADAPTER=oracle_enhanced
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.0.7.gemfile
-      env: DB_ADAPTER=oracle_enhanced
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.1.6.gemfile
-      env: DB_ADAPTER=oracle_enhanced
-    - rvm: 2.4.4
-      gemfile: gemfiles/rails_5.2.0.gemfile
-      env: DB_ADAPTER=oracle_enhanced
 after_success:
   - bundle exec codeclimate-test-reporter
 services:
@@ -77,4 +38,8 @@ env:
   matrix:
     - DB_ADAPTER=postgresql
     - DB_ADAPTER=mysql2
+    - DB_ADAPTER=sqlite3
     - DB_ADAPTER=oracle_enhanced
+matrix:
+  allow_failures:
+    - env: DB_ADAPTER=oracle_enhanced

data/Appraisals

@@ -1,14 +1,6 @@
 # frozen_string_literal: true
 
 RAILS_VERSIONS = {
-  '4.0.13' => {
-    'mysql2' => '~> 0.3.18',
-    'activerecord-oracle_enhanced-adapter' => '~> 1.5.0'
-  },
-  '4.1.16' => {
-    'mysql2' => '~> 0.3.18',
-    'activerecord-oracle_enhanced-adapter' => '~> 1.5.0'
-  },
   '4.2.10' => {
     'activerecord-oracle_enhanced-adapter' => '~> 1.6.0'
   },

data/CHANGELOG.md

@@ -1,12 +1,19 @@
 # CHANGELOG
 
+## 1.0.0 (2018-08-28)
+
+* Breaking change: Remove dependency on view_context [Issue #288](https://github.com/jbox-web/ajax-datatables-rails/issues/288)
+* Breaking change: Replace `config.orm = :active_record` by a class : `AjaxDatatablesRails::ActiveRecord` [Fix #228](https://github.com/jbox-web/ajax-datatables-rails/issues/228)
+
+To mitigate this 2 changes see the [migration doc](/doc/migrate.md).
+
 ## 0.4.3 (2018-06-05)
 
 * Add: Add `:string_eq` condition on columns filter [Issue #291](https://github.com/jbox-web/ajax-datatables-rails/issues/291)
 
 **Note :** This is the last version to support Rails 4.0.x and Rails 4.1.x
 
-## 0.4.2 (2018-05-11)
+## 0.4.2 (2018-05-15)
 
 * Fix: Integer out of range [PR #289](https://github.com/jbox-web/ajax-datatables-rails/pull/289) from [PR #284](https://github.com/jbox-web/ajax-datatables-rails/pull/284)
 

data/README.md

@@ -6,14 +6,13 @@
 [![Build Status](https://travis-ci.org/jbox-web/ajax-datatables-rails.svg?branch=master)](https://travis-ci.org/jbox-web/ajax-datatables-rails)
 [![Code Climate](https://codeclimate.com/github/jbox-web/ajax-datatables-rails/badges/gpa.svg)](https://codeclimate.com/github/jbox-web/ajax-datatables-rails)
 [![Test Coverage](https://codeclimate.com/github/jbox-web/ajax-datatables-rails/badges/coverage.svg)](https://codeclimate.com/github/jbox-web/ajax-datatables-rails/coverage)
-[![Dependency Status](https://gemnasium.com/jbox-web/ajax-datatables-rails.svg)](https://gemnasium.com/jbox-web/ajax-datatables-rails)
 
 **Important : This gem is targeted at DataTables version 1.10.x.**
 
 It's tested against :
 
-* Rails 4.0.13 / 4.1.16 / 4.2.10 / 5.0.7 / 5.1.6 / 5.2.0
-* Ruby 2.2.10 / 2.3.7 / 2.4.4 / 2.5.1
+* Rails 4.2.10 / 5.0.7 / 5.1.6 / 5.2.0
+* Ruby 2.3.7 / 2.4.4 / 2.5.1
 * Postgresql 9.6
 * MySQL 5.6
 * Oracle XE 11.2 (thanks to [travis-oracle](https://github.com/cbandy/travis-oracle))
@@ -40,9 +39,18 @@ All the datatable customizations (header, tr, td, css classes, width, height, bu
 jQuery DataTables is a very powerful tool with a lot of customizations available. Take the time to [read the doc](https://datatables.net/reference/option/).
 
 
-## Warning
+## Warnings
 
-**Breaking changes :** the *v0.4* version is a **major break** from *v0.3*.
+**Breaking changes :**
+
+1) the *v1.0.0* version is a **major break** from *v0.4*.
+
+* Datatables no longer inherits from `AjaxDatatablesRails::Base` but from `AjaxDatatablesRails::ActiveRecord` (this solves [#228](https://github.com/jbox-web/ajax-datatables-rails/issues/228))
+* The `view_context` is no longer injected in Datatables but only the `params` hash (see the [example](#4-setup-the-controller-action)). This will break calls to helpers methods.
+
+To mitigate this 2 changes see the [migration doc](/doc/migrate.md).
+
+2) the *v0.4* version is a **major break** from *v0.3*.
 
 The core has been rewriten to remove dependency on [Kaminari](https://github.com/kaminari/kaminari) or [WillPaginate](https://github.com/mislav/will_paginate).
 
@@ -57,6 +65,13 @@ To migrate on the v0.4 you'll need to :
 * update your views to declare your columns bindings ([See here](#5-wire-up-the-javascript))
 
 
+## Documentation version
+
+This documentation is about the `v1.x.x` release (master branch) of this gem.
+
+You can still have access to the `v0.4.x` documentation on the [v0.4.x branch](https://github.com/jbox-web/ajax-datatables-rails/tree/v0.4.x).
+
+
 ## Installation
 
 Add these lines to your application's Gemfile:
@@ -75,7 +90,7 @@ We assume here that you have already installed [jQuery DataTables](https://datat
 
 You can install jQuery DataTables :
 
-* with the [`jquery-datatables-rails`](https://github.com/rweng/jquery-datatables-rails) gem (which is a bit outdated)
+* with the [`jquery-datatables`](https://github.com/mkhairi/jquery-datatables) gem
 * by adding the assets manually (in `vendor/assets`)
 * with [Rails webpacker gem](https://github.com/rails/webpacker) (see [here](/doc/webpack.md) for more infos)
 
@@ -97,16 +112,11 @@ AjaxDatatablesRails.configure do |config|
 
   # Or you can use your rails environment adapter if you want a generic dev and production
   # config.db_adapter = Rails.configuration.database_configuration[Rails.env]['adapter'].to_sym
-
-  # available options for orm are: :active_record, :mongoid
-  # config.orm = :active_record
 end
 ```
 
 Uncomment the `config.db_adapter` line and set the corresponding value to your database and gem. This is all you need.
 
-Uncomment the `config.orm` line to set `active_record or mongoid` if included in your project. It defaults to `active_record`.
-
 #### Note
 
 Currently `AjaxDatatablesRails` only supports `ActiveRecord` as ORM for performing database queries.
@@ -213,6 +223,22 @@ end
 
 See [here](#columns-syntax) to get more details about columns definitions and how to play with associated models.
 
+You can customize or sanitize the search value passed to the DB by using the `:formatter` option with a lambda :
+
+```ruby
+def view_columns
+  @view_columns ||= {
+    id:         { source: "User.id" },
+    first_name: { source: "User.first_name" },
+    last_name:  { source: "User.last_name" },
+    email:      { source: "User.email", formatter: -> (o) { o.upcase } },
+    bio:        { source: "User.bio" },
+  }
+end
+```
+
+The object passed to the lambda is the search value.
+
 #### b. Map data
 
 Then we need to map the records retrieved by the `get_raw_records` method to the real values we want to display :
@@ -226,7 +252,7 @@ def data
       last_name:  record.last_name,
       email:      record.email,
       bio:        record.bio,
-      DT_RowId:   record.id, # This will set the id attribute on the corresponding <tr> in the datatable
+      DT_RowId:   record.id, # This will automagically set the id attribute on the corresponding <tr> in the datatable
     }
   end
 end
@@ -302,7 +328,7 @@ Set the controller to respond to JSON
 def index
   respond_to do |format|
     format.html
-    format.json { render json: UserDatatable.new(view_context) }
+    format.json { render json: UserDatatable.new(params) }
   end
 end
 ```
@@ -371,7 +397,9 @@ Sometimes you'll need to use view helper methods like `link_to`, `mail_to`,
 To have these methods available to be used, this is the way to go:
 
 ```ruby
-class MyCustomDatatable < AjaxDatatablesRails::Base
+class UserDatatable < AjaxDatatablesRails::ActiveRecord
+  extend Forwardable
+
   # either define them one-by-one
   def_delegator :@view, :check_box_tag
   def_delegator :@view, :link_to
@@ -383,6 +411,11 @@ class MyCustomDatatable < AjaxDatatablesRails::Base
 
   # ... other methods (view_columns, get_raw_records...)
 
+  def initialize(params, opts = {})
+    @view = opts[:view_context]
+    super
+  end
+
   # now, you'll have these methods available to be used anywhere
   def data
     records.map do |record|
@@ -397,11 +430,24 @@ class MyCustomDatatable < AjaxDatatablesRails::Base
     end
   end
 end
+
+# and in your controller:
+def index
+  respond_to do |format|
+    format.html
+    format.json { render json: UserDatatable.new(params, view_context: view_context) }
+  end
+end
 ```
 
+### Using view decorators
+
 If you want to keep things tidy in the data mapping method, you could use
 [Draper](https://github.com/drapergem/draper) to define column mappings like below.
 
+**Note :** This is the recommanded way as you don't need to inject the `view_context` in the Datatable object to access helpers methods.
+It also helps in separating view/presentation logic from filtering logic (the only one that really matters in a datatable class).
+
 Example :
 
 ```ruby
@@ -447,16 +493,9 @@ class UserDecorator < ApplicationDecorator
 end
 ```
 
-**Note :** On the long term it's much more cleaner than using `def_delegator` since decorators are reusable everywhere in your application :)
-
-So we **strongly recommand you to use Draper decorators.** It will help keeping your DataTables class small and clean and keep focused on what they should do (mostly) : filtering records ;)
-
-**Note 2 :** The `def_delegator` might disappear in a near future : [#288 [RFC] Remove dependency on view_context](https://github.com/jbox-web/ajax-datatables-rails/issues/288).
-You're invited to give your opinion :)
-
 ### Pass options to the datatable class
 
-An `AjaxDatatablesRails::Base` inherited class can accept an options hash at initialization. This provides room for flexibility when required.
+An `AjaxDatatablesRails::ActiveRecord` inherited class can accept an options hash at initialization. This provides room for flexibility when required.
 
 Example:
 
@@ -465,12 +504,12 @@ Example:
 def index
   respond_to do |format|
     format.html
-    format.json { render json: UserDatatable.new(view_context, user: current_user, from: 1.month.ago) }
+    format.json { render json: UserDatatable.new(params, user: current_user, from: 1.month.ago) }
   end
 end
 
 # The datatable class
-class UnrespondedMessagesDatatable < AjaxDatatablesRails::Base
+class UnrespondedMessagesDatatable < AjaxDatatablesRails::ActiveRecord
 
   # ... other methods (view_columns, data...)
 
@@ -621,7 +660,7 @@ To enable the date range search, for example `created_at` :
 
 ### Generator Syntax
 
-Also, a class that inherits from `AjaxDatatablesRails::Base` is not tied to an
+Also, a class that inherits from `AjaxDatatablesRails::ActiveRecord` 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:
 
@@ -641,7 +680,25 @@ In the end, it's up to the developer which model(s), scope(s), relationship(s)
 (or else) to employ inside the datatable class to retrieve records from the
 database.
 
-### Creating indices for Postgresql
+## ProTips™
+
+### Create a master parent class
+
+In the same spirit of Rails `ApplicationController` and `ApplicationRecord`, you can create an `ApplicationDatatable` class (in `app/datatables/application_datatable.rb`)
+that will be inherited from other classes :
+
+```ruby
+class ApplicationDatatable < AjaxDatatablesRails::ActiveRecord
+  # puts commonly used methods here
+end
+
+class PostDatatable < ApplicationDatatable
+end
+```
+
+This way it will be easier to DRY you datatables.
+
+### Create indices for Postgresql
 
 In order to speed up the `ILIKE` queries that are executed when using the default configuration, you might want to consider adding some indices.
 For postgresql, you are advised to use the [gin/gist index type](http://www.postgresql.org/docs/current/interactive/pgtrgm.html).
@@ -684,12 +741,81 @@ $ bundle install
 
 That's all :) ([Automatically prefer Yajl or JSON backend over Yaml, if available](https://github.com/rails/rails/commit/63bb955a99eb46e257655c93dd64e86ebbf05651))
 
+### Use HTTP `POST` method
+
+Use HTTP `POST` method to avoid `414 Request-URI Too Large` error. See : [#278](https://github.com/jbox-web/ajax-datatables-rails/issues/278).
+
+You can easily define a route concern in `config/routes.rb` and reuse it when you need it :
+
+```ruby
+Rails.application.routes.draw do
+  concern :with_datatable do
+    post 'datatable', on: :collection
+  end
+
+  resources :posts, concerns: [:with_datatable]
+  resources :users, concerns: [:with_datatable]
+end
+```
+
+then in your controllers :
+
+```ruby
+# PostsController
+  def index
+  end
+
+  def datatable
+    render json: PostDatatable.new(params)
+  end
+
+# UsersController
+  def index
+  end
+
+  def datatable
+    render json: UserDatatable.new(params)
+  end
+```
+
+then in your views :
+
+```html
+# posts/index.html.erb
+<table id="posts-datatable" data-source="<%= datatable_posts_path(format: :json) %>">
+
+# users/index.html.erb
+<table id="users-datatable" data-source="<%= datatable_users_path(format: :json) %>">
+```
+
+then in your Coffee/JS :
+
+```coffee
+$ ->
+  $('#posts-datatable').dataTable
+    ajax:
+      url: $('#posts-datatable').data('source')
+      type: 'POST'
+    # ...others options, see [here](#5-wire-up-the-javascript)
+
+$ ->
+  $('#users-datatable').dataTable
+    ajax:
+      url: $('#users-datatable').data('source')
+      type: 'POST'
+    # ...others options, see [here](#5-wire-up-the-javascript)
+```
+
 ## Tutorial
 
 You'll find a sample project [here](https://github.com/ajahongir/ajax-datatables-rails-v-0-4-0-how-to). Its real world example.
 
 Filtering by JSONB column values : [#277](https://github.com/jbox-web/ajax-datatables-rails/issues/277)
 
+Use [has_scope](https://github.com/plataformatec/has_scope) gem with `ajax-datatables-rails` : [#280](https://github.com/jbox-web/ajax-datatables-rails/issues/280)
+
+Use [Datatable orthogonal data](https://datatables.net/manual/data/orthogonal-data) : see [#269](https://github.com/jbox-web/ajax-datatables-rails/issues/269#issuecomment-387940478)
+
 ## Contributing
 
 1. Fork it

data/ajax-datatables-rails.gemspec

@@ -1,7 +1,6 @@
 # frozen_string_literal: true
-# coding: utf-8
 
-$LOAD_PATH.push File.expand_path('../lib', __FILE__)
+$LOAD_PATH.push File.expand_path('lib', __dir__)
 require 'ajax-datatables-rails/version'
 
 Gem::Specification.new do |s|
@@ -15,9 +14,9 @@ Gem::Specification.new do |s|
   s.description = "A wrapper around datatable's ajax methods that allow synchronization with server-side pagination in a rails app"
   s.license     = 'MIT'
 
-  s.add_dependency 'railties', '>= 4.0'
+  s.add_dependency 'railties', '>= 4.2'
 
-  s.add_development_dependency 'rails', '>= 4.0'
+  s.add_development_dependency 'rails', '>= 4.2'
   s.add_development_dependency 'rake'
   s.add_development_dependency 'pg', '< 1.0'
   s.add_development_dependency 'mysql2'