datatables-net 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 12a1184382aec08a7e808d61beb0340c555407f0
+  data.tar.gz: d62b0eeb7553b308ae4b27018ff8adc06e7eff8e
+SHA512:
+  metadata.gz: 83d8f834fcc37eb94a4c64d7410cd693e3c64198222160b1790fb8cf0315f399dc9f4c2e96718f7778fb1252eb2bbd3b63f5ba85bb3c470bcda2aef2d96ebe15
+  data.tar.gz: 208dc31871ca63e64c2f023558aa849549e1cf7cb63cb481273f4e5cdbfd7fbae115fad7877ed394a0314afb5da66ddefccd32c4f9cb2f150b7c189c473c2f23

data/CHANGELOG.md

@@ -0,0 +1,73 @@
+# CHANGELOG
+
+## 0.4.0
+* Supporting ruby 2.0 and later versions. Rails 3.2 and later version.
+* We have how-to project with special concept on rails_script and coffee_routes gems. https://github.com/ajahongir/ajax-datatables-rails-v-0-4-0-how-to
+* `Datatable.js` idiom based code changes. Now we dont have variables as `sortable_columns` and `searchable_columns` instead we have a hash based `view_columns` variable to define column options. look at readme to more details.
+* Support Searching and Ordering out of box. tested on mysql and sqlihgt.
+
+## 0.3.1
+* Adds `:oracle` as supported `db_adapter`. Thanks to [lutechspa](https://github.com/lutechspa) for this contribution.
+
+## 0.3.0
+* Changes to the `sortable_columns` and `searchable_columns` syntax as it
+  required us to do unnecessary guessing. New syntax is `ModelName.column_name`
+  or `Namespace::ModelName.column_name`. Old syntax of `table_name.column_name`
+  is still available to use, but prints a deprecation warning. Thanks to
+  [M. Saiqul Haq](https://github.com/saiqulhaq) for pointing this.
+* Adds support to discover from received params if a column should be really
+  considered for sorting purposes. Thanks to [Zachariah Clay](https://github.com/mebezac)
+  for this contribution.
+* Moves paginator settings to configuration initializer.
+
+## 0.2.1
+* Fix count method to work with select statements under Rails 4.1. Thanks to
+[Jason Mitchell](https://github.com/mitchej123) for the contribution.
+* Edits to `README` documentation about the `options` hash. Thanks to
+[Jonathan E Hogue](https://github.com/hoguej) for pointing out that previous
+documentation was confusing and didn't address its usage properly.
+* Edits to `README` documentation on complex model queries inside the
+`get_raw_records` method. A round of applause to [Zoltan Paulovics](https://github.com/zpaulovics)
+for contributing this awesome piece of documentation. :smile:
+* Adds typecast step to `search_condition` method, so now we support having
+non-text columns inside the `searchable_columns` array.
+* Adds support for multi-column sorting and multi-term search. Thanks to
+[Zoltan Paulovics](https://github.com/zpaulovics) for contributing this feature.
+* Adds optional config initializer, so we can have a base to typecast non
+text-based columns and perform searches depending on the use of `:mysql2`,
+`:sqlite3` or `:pg`. Thanks to [M. Saiqul Haq](https://github.com/saiqulhaq)
+for contributing this feature.
+
+## 0.2.0
+* This version works with jQuery dataTables ver. 1.10 and it's new API syntax.
+* Added `legacy` branch to repo. If your project is working with jQuery
+  dataTables ver. 1.9, this is the branch you need to pull, or use the last
+  `0.1.x` version of this gem.
+
+## 0.1.2
+* Fixes `where` clause being built even when search term is an empty string.
+  Thanks to [e-fisher](https://github.com/e-fisher) for spotting and fixing this.
+
+## 0.1.1
+* Fixes problem on `searchable_columns` where the corresponding model is
+a composite model name, e.g. `UserData`, `BillingAddress`.
+Thanks to [iruca3](https://github.com/iruca3) for the fix.
+
+## 0.1.0
+* A fresh start. Sets base class name to: `AjaxDatatablesRails::Base`.
+* Extracts pagination functions to mixable modules.
+  * A user would have the option to stick to the base
+    `AjaxDatatablesRails::Extensions::SimplePaginator` or replace it with
+    `AjaxDatatablesRails::Extensions::Kaminari` or
+    `AjaxDatatablesRails::Extensions::WillPaginate`, depending on what he/she
+    is using to handle record pagination.
+* 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.mds#options)
+  for examples.
+* Sets generator inside the `Rails` namespace. To generate an
+  `AjaxDatatablesRails` child class, just execute the
+  generator like this: `$ rails generate datatable NAME`.

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in ajax-datatables-rails.gemspec
+gemspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2012 Joel Quenneville
+
+MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,618 @@
+# ajax-datatables-rails
+
+[![Build Status](https://travis-ci.org/antillas21/ajax-datatables-rails.svg?branch=master)](https://travis-ci.org/antillas21/ajax-datatables-rails)
+[![Gem Version](https://badge.fury.io/rb/ajax-datatables-rails.svg)](http://badge.fury.io/rb/ajax-datatables-rails)
+[![Code Climate](https://codeclimate.com/github/antillas21/ajax-datatables-rails/badges/gpa.svg)](https://codeclimate.com/github/antillas21/ajax-datatables-rails)
+
+> __Important__
+>
+> [Datatables](http://datatables.net) recently released version 1.10 (which includes a new API and features) and deprecated version 1.9.
+>
+> This gem is targeted at Datatables version 1.10 and up.
+
+
+## Description
+
+Datatables is a nifty jquery plugin that adds the ability to paginate, sort,
+and search your html tables. When dealing with large tables
+(more than a couple hundred rows) however, we run into performance issues.
+These can be fixed by using server-side pagination, but this breaks some
+datatables functionality.
+
+`ajax-datatables-rails` is a wrapper around datatable's ajax methods that allow
+synchronization with server-side pagination in a rails app. It was inspired by
+this [Railscast](http://railscasts.com/episodes/340-datatables). I needed to
+implement a similar solution in a couple projects I was working on, so I
+extracted a solution into a gem.
+
+## ORM support
+
+Currently `AjaxDatatablesRails` only supports `ActiveRecord` as ORM for
+performing database queries.
+
+Adding support for `Sequel`, `Mongoid` and `MongoMapper` is a planned feature
+for this gem. If you'd be interested in contributing to speed development,
+please [open an issue](https://github.com/antillas21/ajax-datatables-rails/issues/new)
+and get in touch.
+
+## Installation
+
+Add these lines to your application's Gemfile:
+
+    gem 'jquery-datatables-rails'
+    gem 'ajax-datatables-rails'
+
+And then execute:
+
+    $ bundle
+
+The `jquery-datatables-rails` gem is listed as a convenience, to ease adding
+jQuery dataTables to your Rails project. You can always add the plugin assets
+manually via the assets pipeline. If you decide to use the
+`jquery-datatables-rails` gem, please refer to its installation instructions
+[here](https://github.com/rweng/jquery-datatables-rails).
+
+## Usage (0.3.x)
+*The following examples assume that we are setting up ajax-datatables-rails for
+an index page of users from a `User` model, and that we are using postgresql as
+our db, because you __should be using it__, if not, please refer to the
+[Searching on non text-based columns](#searching-on-non-text-based-columns)
+entry in the Additional Notes section.*
+
+### Generate
+Run the following command:
+
+    $ rails generate datatable User
+
+
+This will generate a file named `user_datatable.rb` in `app/datatables`.
+Open the file and customize in the functions as directed by the comments.
+
+Take a look [here](#generator-syntax) for an explanation about the generator syntax.
+
+
+
+### Build the View
+
+You should always start by the single source of truth, which is your html view. Suppose we need to render a users table and display: first name, last name, and bio for each user.
+
+Something like this:
+
+|First Name|Last Name|Brief Bio|
+|----------|---------|---------|
+|John|Doe|Is your default user everywhere|
+|Jane|Doe|Is John's wife|
+|James|Doe|Is John's brother and best friend|
+
+
+* Set up an html `<table>` with a `<thead>` and `<tbody>`
+* Add in your table headers if desired
+* Don't add any rows to the body of the table, datatables does this automatically
+* Add a data attribute to the `<table>` tag with the url of the JSON feed, in our case is the `users_path` as we're pointing to the `UsersController#index` action
+
+
+```html
+<table id="users-table", data-source="<%= users_path(format: :json) %>">
+  <thead>
+    <tr>
+      <th>First Name</th>
+      <th>Last Name</th>
+      <th>Brief Bio</th>
+    </tr>
+  </thead>
+  <tbody>
+  </tbody>
+</table>
+```
+
+### Customize the generated Datatables class
+```ruby
+def view_columns
+  # Declare strings in this format: ModelName.column_name
+  # or in aliased_join_table.column_name format
+  @view_columns ||= {}
+end
+```
+
+* In this method, add a list of the model(s) columns mapped to the data you need to present. In this case: `first_name`, `last_name` and `bio`.
+
+This gives us:
+
+```ruby
+def view_columns
+  @view_columns ||= {
+    id: { source: "City.id", cond: :eq, searchable: true, orderable: true },
+    name: { source: "City.name", cond: :like },
+    created_at: { source: "City.created_at", cond: :gteq },
+    country_name: { source: "City.country_id", cond: :eq }
+  }
+end
+```
+
+```ruby
+by default orderable and searchable is true
+```
+
+* [See here](#searching-on-non-text-based-columns) for notes about the
+`view_columns` settings (if using something different from `postgre`).
+* [Read these notes](#columns-syntax) about
+considerations for the `view_columns` method.
+
+### Map data
+```ruby
+def data
+  records.map do |record|
+    [
+        # comma separated list of the values for each cell of a table row
+        # example: record.attribute,
+      ]
+  end
+end
+```
+
+This method builds a 2D array that is used by datatables to construct the html
+table. Insert the values you want on each column.
+
+```ruby
+def data
+  records.map do |record|
+    [
+      record.first_name,
+      record.last_name,
+      record.bio
+    ]
+  end
+end
+```
+
+In the example above, we use the same sequence of column declarations as in
+`sortable_columns`. This ordering is important! And as of 0.3.0, the first
+column must be a sortable column. For more, see
+[this issue](https://github.com/antillas21/ajax-datatables-rails/issues/83).
+
+[See here](#using-view-helpers) if you need to use view helpers in the
+returned 2D array, like `link_to`, `mail_to`, `resource_path`, etc.
+
+#### Automatic addition of ID
+If you want the gem inserts automatically the ID of the record in the `<tr>` element
+as shown in this [DataTable example](http://www.datatables.net/examples/server_side/ids.html),
+you have to perform some modifications in both `some_datatable.rb` file and in your javascript.
+
+Here is an example:
+```ruby
+def data
+  records.map do |record|
+    {
+      '0' => record.first_name,
+      '1' => record.last_name,
+      '2' => record.email,
+      'DT_RowId' => record.id
+    }
+  end
+end
+```
+
+and in your javascript file:
+```javascript
+$(function() {
+  return $('#table_id').dataTable({
+    processing: true,
+    serverSide: true,
+    ajax: 'ajax_url',
+    columns: [
+      {data: '0' },
+      {data: '1' },
+      {data: '2' }
+    ]
+  });
+});
+```
+
+#### Get Raw Records
+```ruby
+def get_raw_records
+  # insert query here
+end
+```
+
+This is where your query goes.
+
+```ruby
+def get_raw_records
+  # suppose we need all User records
+  # Rails 4+
+  User.all
+  # Rails 3.x
+  # User.scoped
+end
+```
+
+Obviously, you can construct your query as required for the use case the
+datatable is used. Example: `User.active.with_recent_messages`.
+
+> __IMPORTANT:__ Make sure to return an `ActiveRecord::Relation` object
+> as the end product of this method.
+>
+> Why? Because the result from this method, will be chained (for now)
+> to `ActiveRecord` methods for sorting, filtering and pagination.
+
+#### Associated and nested models
+The previous example has only one single model. But what about if you have
+some associated nested models and in a report you want to show fields from
+these tables.
+
+Take an example that has an `Event, Course, Coursetype, Allocation, Teacher,
+Contact, Competency and CompetencyType` models. We want to have a datatables
+report which has the following column:
+
+```ruby
+        'coursetypes.name',
+        'courses.name',
+        'events.title',
+        'events.event_start',
+        'events.event_end',
+        'contacts.full_name',
+        'competency_types.name',
+        'events.status'
+```
+
+We want to sort and search on all columns of the list. The related definition
+would be:
+
+```ruby
+
+  def view_columns
+    @view_columns ||= [
+        'Coursetype.name',
+        'Course.name',
+        'Event.title',
+        'Event.event_start',
+        'Event.event_end',
+        'Contact.last_name',
+        'CompetencyType.name',
+        'Event.status'
+    ]
+  end
+
+  def get_raw_records
+     Event.joins(
+      { course: :coursetype },
+      { allocations: {
+          teacher: [:contact, {competencies: :competency_type}]
+        }
+      }).distinct
+  end
+```
+
+__Some comments for the above code:__
+
+1. In the `get_raw_records` method we have quite a complex query having one to
+many and may to many associations using the joins ActiveRecord method.
+The joins will generate INNER JOIN relations in the SQL query. In this case,
+we do not include all event in the report if we have events which is not
+associated with any model record from the relation.
+
+2. To have all event records in the list we should use the `.includes` method,
+which generate LEFT OUTER JOIN relation of the SQL query.
+__IMPORTANT:__ Make sure to append `.references(:related_model)` with any
+associated model. That forces the eager loading of all the associated models
+by one SQL query, and the search condition for any column works fine.
+Otherwise the `:recordsFiltered => filter_records(get_raw_records).count(:all)`
+will generate 2 SQL queries (one for the Event model, and then another for the
+associated tables). The `:recordsFiltered => filter_records(get_raw_records).count(:all)`
+will use only the first one to return from the ActiveRecord::Relation object
+in `get_raw_records` and you will get an error message of __Unknown column
+'yourtable.yourfield' in 'where clause'__ in case the search field value
+is not empty.
+
+So the query using the `.includes()` method is:
+
+```ruby
+  def get_raw_records
+     Event.includes(
+      { course: :coursetype },
+      { allocations: {
+          teacher: [:contact, { competencies: :competency_type }]
+        }
+      }
+      ).references(:course).distinct
+  end
+```
+
+For more examples of 0.3.0 syntax for complex associations (and an example of
+the `data` method), read
+[this](https://github.com/antillas21/ajax-datatables-rails/issues/77).
+
+### Setup the Controller action
+
+Set the controller to respond to JSON
+
+```ruby
+def index
+  respond_to do |format|
+    format.html
+    format.json { render json: UserDatatable.new(view_context) }
+  end
+end
+```
+
+Don't forget to make sure the proper route has been added to `config/routes.rb`.
+
+
+* Set up an html `<table>` with a `<thead>` and `<tbody>`
+* Add in your table headers if desired
+* Don't add any rows to the body of the table, datatables does this automatically
+* Add a data attribute to the `<table>` tag with the url of the JSON feed
+
+The resulting view may look like this:
+
+```html
+<table id="users-table" data-source="<%= users_path(format: :json) %>">
+  <thead>
+    <tr>
+      <th>First Name</th>
+      <th>Last Name</th>
+      <th>Brief Bio</th>
+    </tr>
+  </thead>
+  <tbody>
+  </tbody>
+</table>
+```
+
+### Wire up the Javascript
+Finally, the javascript to tie this all together. In the appropriate `coffee` file:
+
+```coffeescript
+# users.coffee
+
+$ ->
+  $('#users-table').dataTable
+    processing: true
+    serverSide: true
+    ajax: $('#users-table').data('source')
+    pagingType: 'full_numbers'
+    # optional, if you want full pagination controls.
+    # Check dataTables documentation to learn more about
+    # available options.
+```
+
+or, if you're using plain javascript:
+```javascript
+// users.js
+
+jQuery(document).ready(function() {
+  $('#users-table').dataTable({
+    "processing": true,
+    "serverSide": true,
+    "ajax": $('#users-table').data('source'),
+    "pagingType": "full_numbers",
+    // optional, if you want full pagination controls.
+    // Check dataTables documentation to learn more about
+    // available options.
+  });
+});
+```
+
+### Additional Notes
+
+#### Columns syntax
+
+Since version `0.3.0`, we are implementing a pseudo code way of declaring
+the array columns to use when querying the database.
+
+Example. Suppose we have the following models: `User`, `PurchaseOrder`,
+`Purchase::LineItem` and we need to have several columns from those models
+available in our datatable to search and sort by.
+
+```ruby
+# we use the ModelName.column_name notation to declare our columns
+
+def view_columns
+  @view_columns ||= [
+    'User.first_name',
+    'User.last_name',
+    'PurchaseOrder.number',
+    'PurchaseOrder.created_at',
+    'Purchase::LineItem.quantity',
+    'Purchase::LineItem.unit_price',
+    'Purchase::LineItem.item_total'
+  ]
+end
+```
+
+##### What if the datatable itself is namespaced?
+Example: what if the datatable is namespaced into an `Admin` module?
+
+```ruby
+module Admin
+  class PurchasesDatatable < AjaxDatatablesRails::Base
+  end
+end
+```
+
+Taking the same models and columns, we would define it like this:
+
+```ruby
+def view_columns
+  @view_columns ||= [
+    '::User.first_name',
+    '::User.last_name',
+    '::PurchaseOrder.number',
+    '::PurchaseOrder.created_at',
+    '::Purchase::LineItem.quantity',
+    '::Purchase::LineItem.unit_price',
+    '::Purchase::LineItem.item_total'
+  ]
+end
+```
+
+Pretty much like you would do it, if you were inside a namespaced controller.
+
+#### What if I'm using Oracle?
+
+We have recently merged and released a contribution from [lutechspa](https://github.com/lutechspa) that makes this gem work with Oracle (tested in version 11g). You can [take a look at this sample repo](https://github.com/paoloripamonti/oracle-ajax-datatable) to get an idea on how to set things up.
+
+#### Searching on non text-based columns
+
+It always comes the time when you need to add a non-string/non-text based
+column to the `@view_columns` array, so you can perform searches against
+these column types (example: numeric, date, time).
+
+We recently added the ability to (automatically) typecast these column types
+and have this scenario covered. Please note however, if you are using
+something different from `postgresql` (with the `:pg` gem), like `oracle`,
+`mysql` or `sqlite`, then you need to add an initializer in your application's
+`config/initializers` directory.
+
+If you don't perform this step (again, if using something different from
+`postgresql`), your database will complain that it does not understand the
+default typecast used to enable such searches.
+
+
+#### Configuration initializer
+
+You have two options to create this initializer:
+
+* use the provided (and recommended) generator (and then just edit the file);
+* create the file from scratch.
+
+To use the generator, from the terminal execute:
+
+```
+$ bundle exec rails generate datatable:config
+```
+
+Doing so, will create the `config/initializers/ajax_datatables_rails.rb` file
+with the following content:
+
+```ruby
+AjaxDatatablesRails.configure do |config|
+  # available options for db_adapter are: :pg, :mysql, :mysql2, :sqlite, :sqlite3, :oracle
+  # config.db_adapter = :pg
+
+  # 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`.
+
+If you want to make the file from scratch, just copy the above code block into
+a file inside the `config/initializers` directory.
+
+
+#### Using view helpers
+
+Sometimes you'll need to use view helper methods like `link_to`, `h`, `mailto`,
+`edit_resource_path` in the returned JSON representation returned by the `data`
+method.
+
+To have these methods available to be used, this is the way to go:
+
+```ruby
+class MyCustomDatatable < AjaxDatatablesRails::Base
+  # either define them one-by-one
+  def_delegator :@view, :link_to
+  def_delegator :@view, :h
+  def_delegator :@view, :mail_to
+
+  # or define them in one pass
+  def_delegators :@view, :link_to, :h, :mailto, :edit_resource_path, :other_method
+
+  # now, you'll have these methods available to be used anywhere
+  # example: mapping the 2d jsonified array returned.
+  def data
+    records.map do |record|
+      [
+        link_to(record.fname, edit_resource_path(record)),
+        mail_to(record.email),
+        # other attributes
+      ]
+    end
+  end
+end
+```
+
+#### 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 }
+)
+```
+So, now inside your class code, you can use those options like this:
+
+
+```ruby
+# let's see an example
+def from
+  @from ||= options[:from].beginning_of_day
+end
+
+def to
+  @to ||= Date.today.end_of_day
+end
+
+def get_raw_records
+  Message.unresponded.where(received_at: from..to)
+end
+```
+
+#### Generator Syntax
+
+Also, a class that inherits from `AjaxDatatablesRails::Base` is not tied to an
+existing model, module, constant or any type of class in your Rails app.
+You can pass a name to your datatable class like this:
+
+
+```
+$ 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.
+
+## Tutorial
+
+Tutorial for Integrating `ajax-datatable-rails`, on  Rails 4.
+
+__version 0.3.0:__
+
+[Part-1  The-Installation](https://github.com/antillas21/ajax-datatables-rails/wiki/Part-1----The-Installation)
+
+[Part 2 The Datatables with ajax functionality](https://github.com/antillas21/ajax-datatables-rails/wiki/Part-2-The-Datatables-with-ajax-functionality)
+
+The complete project code for this tutorial series is available on [github](https://github.com/trkrameshkumar/simple_app).
+
+__version 0.4.0:__
+
+Another sample project [code](https://github.com/ajahongir/ajax-datatables-rails-v-0-4-0-how-to). Its real world example.
+
+## 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