= Simple Datatables

Connects two awesome plugins - Datatables for Jquery and Meta Search together for Rails 3

== Install

Add the following to your Gemfile to install simple datatables:

  gem 'simple_datatables'

After bundle install add this line to rails assets pipeline and restart server:

  //= require simple_datatables

Installation completed.

== Description

There are two ways to map awesome Datatables plugin request fields for Rails.

* First is to convert request on the server side
* Second is to prepare correct request on the client side  

This gem provides interface for the second way. 
To use it you should do the following easy three steps:

Create simple meta_search and will_paginate (optionally) controller action as usual and add ".datatables" format

  respond_to :html, :datatables
  
  def search
    @products = Product.search(params[:search]).paginate(:page => params[:page], :per_page=>params[:per_page])
    respond_with @products
  end

Use standard datatables initializer options for creating table:

* bServerSide: true
* sAjaxSource: path to your controller
* fnServerData: point to simpleDatatables function
* aoColumns: you *should* define all searchable/fiterable sName attributes here. Use format as used in meta_search (with underscores) 

Create Jsonify view with column values for columns listed in aoColumns. View should be written in Jsonify style and should have *.jsonify file extension in order to work properly. See example and Jsonify docs for more details.

== Dependencies

This gem uses:
* meta_search for nice search and sort request syntax mapping
* jsonify for simple output generation 

This gem provides integration with:
* will_paginate for nice pagination request syntax mapping (not bundled)

Gem works only with rails 3.1 and higher.

Gem includes datatables library and fnSetFilteringDelay plugin so you haven't include it by yourself.

Gem does not include any CSS files. Please use styles from datatables website examples.

== Pagination

Simple_datatables is compatible with will_paginate. In order to provide choise freedom you should add will_paginate to your project by yourself. Datatables will provide you "page" and "per_page" request params.

If you do not use pagination do not forget to save search result to some variable with meta_search relation method:

  @products = Product.search(params[:search]).relation

Your can use any other paginator. See below for the details.

== Search for all fields

Note that fulltext search will work only with text fields due to meta_search restrictions. To prevent errors use bSearchable: false for non-text columns in aoColumns field.

== Regex search

Due to meta_search restrictions it is impossible to use regex search for now.

Instead, this gem recognizes bSearch flag as "contains" meta_search finder.

By default "starts_with" is used due to database performance reasons.

Independent fields search will always search using "starts_with" finder.

== Custom pagination implementations

If you are getting strange results (for instance, iTotalRecords and iTotalDisplayRecords both equal 0, or entirely the wrong collection is used), you might want to specify which collection to use:

  @collection = @products
  respond_with @products

Also if you are using own or uncommon implementation of pagination you may use direct page count variables setting as follows:

  @total_entries = 12
  @current_page_entries = 10
  respond_with @products

In this case gem will not try to find collection or pagination and will use the counters passed via variables.

== Example

The following code will show products list datatables. Manufacturer is belongs_to association for Product.

First of all add to your routes.rb datatables search api method:

  resources :products do
    collection do
      get :search
    end
  end

Then implement it in your controller:

  respond_to :html, :datatables
  
  # GET /products/search
  def search
    @products = Product.search(params[:search]).paginate(:page => params[:page], :per_page=>params[:per_page])
    respond_with @products
  end

In your search view (app/views/products/search.jsonify) implement output fields order:

  @products.each do |product|
    json << [product.name, product.manufacturer.name]
  end

In your index view make a table with header (HAML):

  %table#products
    %thead
      %tr
        %th= Product.human_attribute_name :name
        %th= Product.human_attribute_name :manufacturer
  
    %tbody

In your javascript add the following code to initialize the datatables (be sure to do it after document load):

  $("#products").dataTable({
      "sAjaxSource"     : "/products/search.datatables",
      "aaSorting"       : [[0, 'asc']],
      "aoColumns"       : [
        {"sName":"name"},
        {"sName":"manufacturer_name"},
      ],
      "bServerSide"     : true,
      "fnServerData"    : simpleDatatables
    });

== Copyright

Copyright (c) Grigory Dmitrenko, 2012. See LICENSE for details.