SortingTableFor

Introduction

SortingTableFor is a Rails TableBuilder made to easily create table or sort a table. The syntax is simple to write and easy to read.

Infos

It's Rails 2 and Rails 3 compatible
I18n compatible

Installation

In Rails 3, add this to your Gemfile.

gem "sorting_table_for", '> 0.2.1'

In Rails 2, add this to your environment.rb file.

config.gem "sorting_table_for", '0.2.2'

Alternatively, you can install it as a plugin.

rails plugin install git://github.com/arkes/sorting_table_for.git

Usage

To create a quick table

<% sorting_table_for @users do |table| %>
  <%= table.headers %>
  <%= table.columns %>
<% end %>

will render

<table>
  <thead>
    <tr>
      <th class='cur-sort-not'><a href='/my_link?table_sort[username]=asc'>...</a></th>
      <th class='cur-sort-not'><a href='/my_link?table_sort[firstname]=asc'>...</a></th>
      <th>Edit</th>
      <th>Delete</th>
    </tr>
  </thead>
  <tbody>
    <tr>
      <td colspan='4' class='total-entries'>Total Entries: 2</td>
    </tr>
    <tr>
      <td>Test</td>
      <td>Myname</td>
      <td><a href='/users/1/edit'>Edit</a></td>
      <td><a href='/users/1'>Delete</a></td>
    <tr>
  </tbody>
</table>

column and header can be called with a list

<% sorting_table_for @users do |table| %>
  <%= table.headers :username, :firstname, :lastname %>
  <%= table.columns :username, :firstname, :lastname %>
<% end %>

On columns you can get the current object of your collection. You can give to column or header whatever you want: symbol, string, image, ...

<% sorting_table_for @users do |table| %>
  <%= table.headers do %>
    <%= table.header :username %>
    <%= table.header :firstname %>
    <%= table.header image_tag('rails.png') %>
  <% end %>
  <%= table.columns do |user| %>
    <%= table.column :username %>
    <%= table.column user.firstname %>
    <%= table.column 'exemple' %>
  <% end %>
<% end %>

column and header can be called with a block

<% sorting_table_for @users do |table| %>
  <%= table.headers do %>
    <%= table.header do %>
      <%= image_tag('rails.png') %>
    <% end %>
  <% end %>
  <%= table.columns do |user| %>
    <%= table.column do %>
      <%= user.username.downcase %>
    <% end %>
  <% end %>
<% end %>

You can set a footer to the table, it can be called with a list or a block

<% sorting_table_for @users do |table| %>
  <%= table.footers :footer %>
<% end %>

-- equivalent --

<% sorting_table_for @users do |table| %>
  <%= table.footers do %>
    <%= table.footer :footer %>
  <% end %>
<% end %>

Caption

Create a tag caption to set a title to the table, it can be called with or without a block

<% sorting_table_for @users do |table| %>
  <%= table.caption 'my title' %>
<% end %>

Options

:html => Hash options: class, id, ...
:as => Force to render a type (:date, :time, :currency)
:format => Set the I18n localization format for :date or :time (:default, :short, ...)
:action => Set an action
:caption => Set caption on td
:actions => Set actions to render
:only => Columns to render (on list)
:except => Columns to not render (on list)
:sort => Add or not sorting (true of false)

Options for sorting table for

:builder => Set a table builder
:html => Set html options (id, class, ...)
:remote_link => To set actions link with ajax (true or false)
:remote_sort => To set link for sorting with ajax (true of false)
:i18n => To use or not i18n on values (true or false)

Exemple

<% sorting_table_for @users do |table| %>
  <%= table.headers do %>
    <%= table.header :username %>
    <%= table.header :price, :sort => false %>
    <%= table.header :created_at %>
    <%= table.header 'today' %>
  <% end %>
  <%= table.columns do |user| %>
    <%= table.column user.username %>
    <%= table.column user.price, :as => :currency %>
    <%= table.column user.created, :as => :date %>
    <%= table.column DateTime.now, :as => :datetime, :format => :short %>
  <% end %>
<% end %>

Exemple with action

<% sorting_table_for @users do |table| %>
  <%= table.headers do %>
    <%= table.header :username %>
    <%= table.header :action => :edit %>
  <% end %>
  <%= table.columns do |user| %>
    <%= table.column user.username, :action => :show %>
    <%= table.column :action => :edit %>
  <% end %>
<% end %>

Exemple with html

<% sorting_table_for @users, :html => { :class => 'my_table' } do |table| %>
  <%= table.headers :html => { :class => 'my_headers', :title => 'column !' } do %>
    <%= table.header :username :html => { :class => 'header_username' } %>
    <%= table.header :firstname :html => { :title => 'hello price' } %>
  <% end %>
  <%= table.columns :html => { :class => 'my_columns' } do |user| %>
    <%= table.column :username :html => { :class => 'column_username' }%>
    <%= table.column :firstname :html => { :title => "it's #{user.firstname}" } %>
  <% end %>
<% end %>

Namespace

SortingTableFor can use your namespace

<% sorting_table_for [:admin, @users] do |table| %>
  <%= table.headers %>
  <%= table.columns %>
<% end %>

Sorting

To add sort in your query, you just have to add sorting_table in your query

def index
  @users = User.sorting_table(params).all
end

to add a default sorting

def index
  @users = User.sorting_table(params, :username).all
end

-- or --

def index
  @users = User.sorting_table(params, :username, :desc).all
end

Ajax

You can add ajax on sorting

    <% sorting_table_for @users, :sort_remote => true do |table| %>
      <%= table.headers %>
      <%= table.columns %>
    <% end %>

You can add ajax on links

    <% sorting_table_for @users, :link_remote => true do |table| %>
      <%= table.headers %>
      <%= table.columns %>
    <% end %>

Configurations

There are some options that you can modify in your initiatilizer

see the initializer file exemple for more explanation

Stylesheet

Class 'odd' or 'even' on rows
Class 'cur-sort-not', 'cur-sort-asc' or 'cur-sort-desc' on sorting headers
Class 'total-entries' on total entries

Here an exemple of css file