flexible_datatables 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: a13f848d1e7169a66d108830a47d8289e6476c33
+  data.tar.gz: 3d2bfa335369d77870971e5085a5a70bb26171ed
+SHA512:
+  metadata.gz: d1dae4b484f9791480a47c4a9ffdb968f074f5c09bf13a9e21a4b9aa347a21a05e479e38b2ddfe2bcd468d54249f4c536fa48d9c1f29d5ab2f3dbd15f3122759
+  data.tar.gz: eb9b00b5cf65177cd9f05671a4b51ebe91e9319e68c3ce5cf0f031f0e765486d26cafb827c0550230a67bab8df1f985ef2cb53ede217e7cda5393cfe6c9f720b

data/CHANGELOG

@@ -0,0 +1,9 @@
+Change Log
+==========
+
+All notable changes to the project are documented in this file.
+
+[1.0.0] - 2015-02-14
+--------------------
+
+Version 1 release of the library.

data/CHANGELOG.md

@@ -0,0 +1,9 @@
+Change Log
+==========
+
+All notable changes to the project are documented in this file.
+
+[1.0.0] - 2015-02-14
+--------------------
+
+Version 1 release of the library.

data/README.md

@@ -0,0 +1,112 @@
+# Flexible Datatables
+
+Easily integrate [JQuery Datatables](https://www.datatables.net) (with Ajax) into your Ruby / Rails web applications.
+
+## Introduction
+Flexible Datatables wraps array-like objects (ActiveRecord::Relation collections, etc) that JQuery Datatables can read (via ajax) from your Ruby / Rails web application.
+
+## Features
+* Any arbitrary array-like collection of data, from plain old ruby arrays to complicated ActiveRecord (or Arel, or plain SQL) query results, can be passed on to JQuery Datatables with very little configuration overhead.
+* Server-side pagination with [Kaminari](https://github.com/amatsuda/kaminari) can be used, out of the box.
+
+## Background
+This library was inspired by Ryan Bates' excellent [Railscast episode](http://railscasts.com/episodes/340-datatables) and the [ajax-datatables-rails](https://github.com/antillas21/ajax-datatables-rails) gem.
+
+So why not just use [ajax-datatables-rails](https://github.com/antillas21/ajax-datatables-rails)?
+
+1. I wanted to be free to use (abuse) SQL to generate the result set to be passed to DataTables.  The [ajax-datatables-rails](https://github.com/antillas21/ajax-datatables-rails) library constructs ActiveRecord queries on the application's behalf, based on user-supplied column names.
+2. I also wanted to the ability to sort on any kind of column, from integer column types to non-string / non-text based columns, to aggregate functions, and so on.
+3. Although I usually choose PostgreSQL as my Rails DB backend of choice, I wanted to be able to pass in any kind of array-like collection (or even use a different database backend altogether).
+
+## Installation
+1. First, make sure you have [DataTables](https://www.datatables.net) installed.
+
+    You have a few choices here.  If you are integrating DataTables with a Rails project, the easiest route is via the [jquery-datatables-rails](https://github.com/rweng/jquery-datatables-rails) gem.  Be sure to follow the installation instructions if you choose this route.
+
+    You can also use [bower](https://github.com/rharriso/bower-rails), or you can even leverage DataTables' [cdn](https://cdn.datatables.net/).
+
+2. Add this line to your application's `Gemfile`:
+
+        gem 'flexible_datatables'
+
+    And then execute:
+
+        $ bundle
+
+    Or install it yourself as:
+
+        $ gem install flexible_datatables
+3. (optional)  Create the file `config/initializers/flexible_datatables.rb`.  You can use this to override default values (such as the choice of pagination).
+```ruby
+FlexibleDatatables.configuration do |settings|
+  # settings.paginator = FlexibleDatatables::KaminariPaginator
+  settings.paginator = FlexibleDatatables::SimplePaginator
+  # settings.items_per_page = 10
+end
+```
+
+## Usage
+### Rails
+*NOTE*
+
+Flexible Datatables isn't required if you wish to use DataTables to transform an html `table` without using ajax (see the first part of the [DataTables RailsCast](http://railscasts.com/episodes/340-datatables?view=asciicast) for reference).
+
+The benefit of using Flexible Datatables comes when one wishes to have DataTables tables displaying data from a Rails backend using ajax.
+
+#### Controller
+Flexible Datatables requires the `draw`, `start`, `length`, and `order` keys from the `params` hash.  Initialize a new `FlexibleDatatables::Datatable` object and pass in those values.
+```ruby
+datatable = FlexibleDatatables::Datatable.new(params.slice(:draw, :start, :length, :order))
+```
+Pass in a collection of objects (which can come from anywhere; an array, an ActiveRecord query, etc)
+```ruby
+datatable.collection = MyModel.all
+```
+Tell your `Datatable` object what your columns are and how to arrange them into rows.
+```ruby
+datatable.format_grid(%w(first_column, second_column, third_column) do |record|
+ [record.first_column, record.second_column, record.third_column]
+end
+```
+Instruct Rails to render your `Datatable` object as `JSON`.  Your controller may look something like this:
+```ruby
+respond_to do |format|
+ format.html
+ format.json do
+   datatable = FlexibleDatatables::Datatable.new(params.slice(:draw, :start, :length, :order))
+   datatable.collection = MyModel.all
+   datatable.format_grid(%w(first_column, second_column, third_column) do |record|
+     [record.first_column, record.second_column, record.third_column]
+   end
+   render json: datatable
+   end
+end
+```
+
+#### View
+Define a `table` with an `id` attribute.
+Give the `table` a `data-source` attribute that points to the route that DataTables will use to get the json data over ajax.
+Give this `table` a `thead` with some header columns, and an empty `tbody` declaration.
+
+#### JavaScript
+Finally, in a javascript file, call `.DataTable()` and pass in values for the `processing`, `serverSide`, `ajax`, and `pagingType` parameters.
+```Coffeescript
+$ ->
+  $('#my_table_id').DataTable
+    processing: true
+    serverSide: true
+    ajax: $('#my_table_id').data('source')
+    pagingType: "full_numbers"
+```
+
+## 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
+
+## License
+
+GPL-3.0+

data/lib/flexible_datatables.rb

@@ -0,0 +1,16 @@
+module FlexibleDatatables
+  def self.configuration
+    Configurator.configuration do |config|
+      yield(config)
+    end
+  end
+
+  def self.settings
+    Configurator.settings
+  end
+end
+
+require 'ostruct'
+require 'flexible_datatables/datatable'
+require 'flexible_datatables/configurator'
+require 'flexible_datatables/paginators'

data/lib/flexible_datatables/configurator.rb

@@ -0,0 +1,21 @@
+module FlexibleDatatables
+  module Configurator
+    class Settings
+      attr_accessor :items_per_page, :paginator
+
+      def initialize
+        @items_per_page = 10
+        @paginator = DummyPaginator
+      end
+    end
+
+    def self.configuration
+      @@settings ||= Settings.new
+      yield(@@settings)
+    end
+
+    def self.settings
+      @@settings
+    end
+  end
+end

data/lib/flexible_datatables/datatable.rb

@@ -0,0 +1,49 @@
+module FlexibleDatatables
+  class Datatable
+    attr_accessor :collection, :columns
+
+    def initialize(args = {})
+      @columns   = []
+      @draw      = args.fetch(:draw).to_i
+      @grid      = []
+      @length    = args.fetch(:length, Configurator.settings.items_per_page).to_i
+      @order     = args.fetch(:order, {})
+      @paginator = args.fetch(:paginator, Configurator.settings.paginator)
+      @start     = args.fetch(:start, 0).to_i
+    end
+
+    def as_json(options = {})
+      {
+        draw:            draw,
+        recordsTotal:    collection.length,
+        recordsFiltered: collection.length,
+        data:            @grid
+      }
+    end
+
+    def format_grid(cols)
+      @columns = cols unless cols.blank?
+      records = collection.order("#{sort_column} #{sort_direction}")
+      @grid = paginate(records).map { |record| yield(record) }
+    end
+
+    private
+    attr_reader :draw,
+                :length,
+                :order,
+                :paginator,
+                :start
+
+    def sort_column
+      @columns[order["0"].fetch(:column).to_i]
+    end
+
+    def sort_direction
+      order["0"].fetch(:dir) == "desc" ? "desc" : "asc"
+    end
+
+    def paginate(records)
+      paginator.paginate(start: start, length: length, records: records)
+    end
+  end
+end

data/lib/flexible_datatables/paginators.rb

@@ -0,0 +1,3 @@
+require 'flexible_datatables/paginators/dummy_paginator'
+require 'flexible_datatables/paginators/simple_paginator'
+require 'flexible_datatables/paginators/kaminari_paginator'

data/lib/flexible_datatables/paginators/dummy_paginator.rb

@@ -0,0 +1,7 @@
+module FlexibleDatatables
+  module DummyPaginator
+    def self.paginate(args = Hash.new)
+      args.fetch(:records, [])
+    end
+  end
+end

data/lib/flexible_datatables/paginators/kaminari_paginator.rb

@@ -0,0 +1,12 @@
+module FlexibleDatatables
+  module KaminariPaginator
+    def self.paginate(args = Hash.new)
+      per_page = args.fetch(:length, 0).to_i
+      per_page = Configurator.settings.items_per_page unless per_page > 0
+      page     = args.fetch(:start, 0).to_i / per_page + 1
+
+      records  = args.fetch(:records, [])
+      records.page(page).per(per_page)
+    end
+  end
+end

data/lib/flexible_datatables/paginators/simple_paginator.rb

@@ -0,0 +1,12 @@
+module FlexibleDatatables
+  module SimplePaginator
+    def self.paginate(args = Hash.new)
+      per_page = args.fetch(:length, 0).to_i
+      per_page = Configurator.settings.items_per_page unless per_page > 0
+      start    = args.fetch(:start, 0).to_i
+
+      records  = args.fetch(:records, [])
+      records.slice(start, per_page)
+    end
+  end
+end

data/lib/flexible_datatables/version.rb

@@ -0,0 +1,3 @@
+module FlexibleDatatables
+  VERSION = '1.0.0'
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: flexible_datatables
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Dave Corning
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2015-02-14 00:00:00.000000000 Z
+dependencies: []
+description: Flexible Datatables wraps array-like objects (ActiveRecord::Relation
+  collections, etc) that JQuery Datatables can read (via ajax) from your Ruby / Rails
+  web application.
+email: dave@davecorning.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG
+- CHANGELOG.md
+- README.md
+- lib/flexible_datatables.rb
+- lib/flexible_datatables/configurator.rb
+- lib/flexible_datatables/datatable.rb
+- lib/flexible_datatables/paginators.rb
+- lib/flexible_datatables/paginators/dummy_paginator.rb
+- lib/flexible_datatables/paginators/kaminari_paginator.rb
+- lib/flexible_datatables/paginators/simple_paginator.rb
+- lib/flexible_datatables/version.rb
+homepage: https://github.com/davecorning/flexible_datatables
+licenses:
+- GPL-3.0+
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.4.5
+signing_key: 
+specification_version: 4
+summary: Easily integrate JQuery Datatables (with Ajax) into your Ruby / Rails web
+  applications.
+test_files: []