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.3.0'
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 %>
Footer
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
Copyright (c) 2010 arkes (Thomas Floch), released under the MIT license