Skip to content


Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time


A simpler, Rails-friendly interface to using the DataTables jQuery library.


Make sure you have jQuery.js and jQuery.dataTables.js in /public/javascripts/ and that they're included in your layout.


Give table a class of 'datatable' so that the Javascript knows which table to alter. NOTE: If you want to use multiple tables on a single page, include the :table_dom_id in the options hash to specify the ID table to be altered.

Add thead around the table header (These elements will associate to the columns array created below, allowing sorting).

Add tbody around the table rows (These are the elements that will be sorted and paginated.)

Activate using <%= datatable() %>, passing in the columns, how to filter them (sorting type), and any other settings (ajax source, search?, label for search, processing image)

<% columns = [{:type => 'html', :class => "first"}, {:type => 'html'}, {:type => 'html'}, {:type => nil, :class => "last"}] %>
<%= datatable(columns, {:sort_by => "[0, 'desc']", :processing => image_tag("spinner.gif") }) %>

<table id='users' class='datatable'>
      <th>Account Level</th>
    <%- @users.each do |user| -%>
      <tr id="<%= dom_id(user) %>">
        <td><%= %></td>
        <td><%= %></td>
        <td><%= %></td>
        <td><%= link_to "Edit", edit_system_user_path(user) %></td>
    <%- end -%>


Table Options

:sort_by - array, default column number (0 - n-1) and sort order. e.g. "[2, 'desc']". Defaults to initial order.
:search - boolean, display the search field. Defaults to true.
:search_label - string, the label for the search field. Defaults to "Search".
:processing - string, the text or image to display while processing data. Defaults to "Processing".
:persist_state - boolean, remember the sorting and page of the tables for the user. Defaults to true.
:additional_data - hash, pass along additional data, such as filter values. Default is none.
:table_dom_id - string, the ID of the table to alter. If nothing is passed, it will look for a class of 'datatable'. Necessary if you want to have multiple DataTables on a single page.
:per_page - the number of rows to show per page (renamed from display_length)
:append - functions to all at the end of the dataTable() call. Useful for [Datatables plugins](
:no_records_message - Message to display if no records are found, whether on load or after searching
:auto_width - Automatically adjust the width of the columns. Defaults to true.
:row_callback - a function to run on each row in the table. Inserted in to "'fnRowCallback': function( nRow, aData, iDisplayIndex ) {  }". See [documentation for fnRowCallback]( for more information.

Column Options

:class - string, the class to assign to the table cell. Default is none.
:type - string, the type of content in the column, for non-Ajax tables. 'html' will strip all HTML and sort on the inner value, as a string. Default is string.
:sortable - boolean, allow this column to be sorted on. Default is true.
:searchable - boolean, allow this column to be searched, for non-Ajax tables. Default is true.

AJAX Options

When you're working with large datasets it's not reasonable to load everything on page load. Use an :ajax_source to load just the records that are being displayed, do custom searching (DB, Solr, etc).

:ajax_source - string, for large datasets, use an ajax source to load each page on its own. For smaller datasets, just load the whole set and let datatable do the sorting

Add a datatable method on your controller to return JSON

  • Return the objects to be displayed
  • Return the total number of objects
  • Add a method to handle sorting - DataTables returns the column that is being sorted (0 - n), so you need to know which column is which and sort on it.

AJAX Example

Datatable view example - datatable.html.erb

{"sEcho": <%= params[:sEcho] || -1 %>,
 "iTotalRecords": <%= @total_objects %>,
 "iTotalDisplayRecords": <%= @total_object %>,
<% @objects.each do |object| %>
  ['<%= link_to(, user) %>',
   '<%= object.description || "-" %>',
   '<%= object.created_at %>'
<% end %>

Controller example - using will_paginate

def datatable
  @objects = current_objects(params)
  @total_objectss = total_objects(params)
  render :layout => false


def current_objects(params={})
  current_page = (params[:iDisplayStart].to_i/params[:iDisplayLength].to_i rescue 0)+1
  @current_objects = Object.paginate :page => current_page, 
                                     :include => [:user], 
                                     :order => "#{datatable_columns(params[:iSortCol_0])} #{params[:sSortDir_0] || "DESC"}", 
                                     :conditions => conditions,
                                     :per_page => params[:iDisplayLength]

def total_objects(params={})
  @total_objects = Object.count :include => [:user], :conditions => conditions

def datatable_columns(column_id)
  case column_id.to_i
  when 1
    return "objects.description"
  when 2
    return "objects.created_at"
    return ""

def conditions
  conditions = []
  conditions << "(objects.description ILIKE '%#{params[:sSearch]}%' OR ILIKE '%#{params[:sSearch]}%')" if(params[:sSearch])
  return conditions.join(" AND ")


There is a more functionality offered by DataTables than this plugin currently provides. We add to it as we find need for other features. If there's a feature of DataTables that you'd like to see, fork this repo and add it so we can all benefit.


Copyright (c) 2009 Phronos, released under the MIT license


Rails plugin for the jQuery Datatables library







No releases published


No packages published