README

Datatables
==========

Rails 3 plugin for adding JQuery DataTables to your application.

DataTables: http://datatables.net/index

Requirements:

JQuery, JQuery UI, and the DataTables JQuery plugin

Features:

Easy definition of a table for an ActiveRecord model.
Supports pagination using will_paginate.
Supports sorting.


TODO
=======

Add tests.


Example
=======

In your controller, set up a datatables source. This is how the data is pulled from the server and returned with AJAX.

Controller
===========

datatables_source :users_source, :user, :columns => [
  :username, :fullname, {:name => "updated_at", :eval => 'obj.updated_at.getlocal.rfc2822'},
  {:name => "Options", :method => :user_options_column}]

This defines a table, named users_source, for the User model.

The columns are (in order):

username, fullname, updated_at, and options

There are two special ways to display the data for a column/row.

eval:

Evaluates a string, "obj" is an instance of your model in the table (in this case, a User object).


method:

Calls a method in your controller with the instance of your model as the parameter.

When defining a method for a column, an example method in your controller would be:

def user_options_column(user)
  "<a href=\"#{url_for :action => 'view', :id => user.id}\">View User</a>"
end

options:
-------
In addition to :column, additional options can be passed in:

:conditions (conditions that will be ANDed to any search query)
:join_tables (if you need to include any additional ActiveRecord table relationships from belongs_to/etc.)

example that will show both the tweet and the user who the tweet belong to:
 datatables_source :tweets_source, :tweet, :columns => [
    {:name => "Actions", :method => :datatables_actions_column},
    :name, {:name=>"User", :method => :tweet_user_column } ],
   :conditions => ['censorsed=0'],
   :join_tables => ['user']

Known Issue - cannot sort/filter by joined tables


Routes
=========

Because DataTables uses AJAX to load the data in the table, you must define a route to it. The first parameter of datatables_source is a *named route*. The rails plugin uses this to link the HTML for your DataTable.

Example
=========

match 'datatables/user' => "user#users_source", :as => "users_source"


Displaying the table
=========================

Displaying a table is probably the easiest part. In a view for your controller, you just do the following:

<%= datatables :users_source %>


Copyright (c) 2010 Chris Moos, released under the MIT license
Copyright (c) 2011 Ilia Lobsanov, released under the MIT license