killthekitten / table-for

A view simple and useful table builder for a collection of objects

table-for¶ ↑

Table-for is a table builder for a collection of domain objects. It very easily allows the user to specify the columns to render and to override how the table, the header columns, the rows, and the columns are rendered.

Installation¶ ↑

In Rails 3, add this to your Gemfile.

gem "table-for"

In this example, I’m going to assume the following setup: From the console, I have generated a user model with email, first_name, and last_name fields, and generated a scaffold on that model

rails g scaffold user email:string first_name:string last_name:string --no-stylesheets

In seeds.rb:

User.create! :email => "[email protected]", :first_name => "Andrew", :last_name => "Hunter"
User.create! :email => "[email protected]", :first_name => "Todd", :last_name => "Fisher"
User.create! :email => "[email protected]", :first_name => "Jon", :last_name => "Phillips"

In users_controller.rb (index action)

@users = User.all

Sample Usage¶ ↑

<%= table_for @users, :table_html => {:style => "border: 1px solid black"},
                      :sortable => true, :sort_url => users_path,
                      :row_html => {:class => lambda { cycle('even', 'odd')},
                                    :id => lambda {|user| "user-#{user.id}"}} do |table| %>
  <% table.column :edit, :link_label => "Modify" %>
  <% table.column :show %>
  <% table.column :email, :label => "Email Address" %>
  <% table.column :label => "Full Name", :sortable => false, :header_html => {:style => "color:orange"} do |user| %>
    <%= "#{user.first_name} #{user.last_name}" %>
  <% end %>
  <% table.column :delete, :confirm => "Are you sure?" %>
<% end %>

Specifying the Columns to Use¶ ↑

<%= table_for @users do |table| %>
  <% table.column :email %>
  <% table.column :first_name %>
  <% table.column :last_name %>
<% end %>

Here, each column will send its respective column name to the user object: user.send(:email), user.send(:first_name), user.send(:last_name), to determine what data to output in each column.

Specifying the Label to Use for a Column¶ ↑

<%= table_for @users do |table| %>
  <% table.column :email, :label => "Email Address" %>
<% end %>

Overriding the Default Way of Rendering a Column¶ ↑

<%= table_for @users do |table| %>
  <% table.column :name do |user| %>
    <%= "#{user.first_name} #{user.last_name}" %>
  <% end %>
<% end %>

<!-- Or, since the name of the column is no longer used to figure out what data to render: -->
<%= table_for @users do |table| %>
  <% table.column :full_name do |user| %>
    <%= "#{user.first_name} #{user.last_name}" %>
  <% end %>
<% end %>

<!-- Or the block name could be removed altogether and replaced with a label: -->
<%= table_for @users do |table| %>
  <% table.column :label => "Full Name" do |user| %>
    <%= "#{user.first_name} #{user.last_name}" %>
  <% end %>
<% end %>

Specifying Sortability¶ ↑

<!-- Globally: -->
<%= table_for @users, :sortable => true, :sort_url => users_path do |table| %>
  <% table.column :id, :sortable => false %>
  <% table.column :email %>
  <% table.column :name, :order => "first_name,last_name" do |user| %>
    <%= "#{user.first_name} #{user.last_name}" %>
  <% end %>
<% end %>

<!-- Column by column basis: -->
<%= table_for @users, :sort_url => users_path do |table| %>
  <% table.column :id %>
  <% table.column :email, :sortable => true %>
  <% table.column :name, :order => "first_name,last_name", :sortable => true do |user| %>
    <%= "#{user.first_name} #{user.last_name}" %>
  <% end %>
<% end %>

Specifying the Table HTML¶ ↑

<%= table_for @users, :table_html => {:class => "table-for-table", :style => "border:1px solid black"} %>

Specifying the Row HTML¶ ↑

<!-- Header row -->
<%= table_for @users, :header_row_html => {:style => "background-color:blue", :class => "table-header"} do |table| %>
  <% table.column :email %>
<% end %>

<!-- Data rows -->
<%= table_for @users, :row_html => {:style => "background-color:blue",
                                    :class => lambda {"table-row #{cycle('even', 'odd')}"},
                                    :id => lambda {|user| "user-#{user.id}"}} do |table| %>
  <% table.column :email %>
<% end %>

Specifying the Column HTML¶ ↑

<!-- Header columns -->
<%= table_for @users, :header_html => {:class => lambda {|column| "header-column #{column.name}"} } do |table| %>
  <!-- Override this columns' header's html -->
  <% table.column :email, :header_html => {:style => "color: red"} %>
  <% table.column :first_name %>
  <% table.column :last_name %>
<% end %>

<!-- Data columns -->
<%= table_for @users, :column_html => {:class => lambda {|column| "data-column #{column.name}"} } do |table| %>
  <!-- Override this column's html -->
  <% table.column :email, :column_html => {:style => "background-color: red"} %>
  <% table.column :first_name %>
  <% table.column :last_name %>
<% end %>

Using Show, Edit, and Delete Columns¶ ↑

<%= table_for @users do |table| %>
  <!-- Standard show link -->
  <% table.column :show %>

  <!-- Specify the controller action for the show link (used for generating the link) -->
  <% table.column :show, :action => :display %>

  <!-- Standard edit link -->
  <% table.column :edit %>

  <!-- Specify the text for the edit link -->
  <% table.column :edit, :link_label => "Modify" %>

  <!-- Specify the url for the edit link -->
  <% table.column :edit, :url => lambda {|user| edit_user_path(user) } %>

  <!-- Specify the controller action for the edit link (used for generating the link) -->
  <% table.column :edit, :action => :modify %>

  <!-- Specify the scope for the edit link (i.e. for nested resources) -->
  <% table.column :edit, :scope => :admin %>

  <!-- Specify the confirmation message for the confirm link -->
  <% table.column :delete, :confirm => "Are you sure???" %>
<% end %>

Using “Before” and “After” hooks¶ ↑

<!-- Adding a table footer -->
<%= table_for @users do |table| %>
  <% table.column :email %>
  <% table.define :footer do %>
    <tfoot><tr><td colspan="<%= table.columns.length %>">My Footer</td></tr></tfoot>
  <% end %>
<% end %>

<!-- Evaluating an expression before each row renders -->
<%= table_for @users do |table| %>
  <% table.before :row do |user| %>
    <!-- Perform some calculation -->
    <% @evaluated_data = user.do_some_method %>
  <% end %>
  <% table.column :label => "First Column" do |user| %>
    <!-- Use the stored value in some way -->
    <%= @evaluated_data.method_1 %>
  <% end %>
  <% table.column :label => "Second Column" do |user| %>
    <!-- Use the stored value in some other way -->
    <%= @evaluated_data.method_2 %>
  <% end %>
<% end %>

<!-- Adding a row before all the data rows -->
<%= table_for @users do |table| %>
  <% table.before :rows do %>
    <tr><td colspan="<%= table.columns.length %>">My First Row</td></tr>
  <% end %>
  <% table.column :email %>
<% end %>

Changing the Default Way table_for Renders¶ ↑

<!-- Don't render thead and tbody tags -->
<%= table_for @users do |table| %>
  <% table.define :table do |options| %>
    <%= content_tag :table, options[:table_html] do %>
      <!-- Instead of table.render :header, do this -->
      <%= table.render :header_row %>
      <!-- Instead of table.render :body, do this -->
      <%= table.render :rows %>
    <% end %>
  <% end %>
  <% table.column :email %>
<% end %>