table-for

TableFor 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 or Rails 4, add this to your Gemfile.

gem "table-for", :git => "[email protected]:hunterae/table-for.git"

Example

The following example is purposely complex (in many cases, there are easier ways to do what is shown) in order to show a wide range of features that TableFor is capable of:

<%= table_for @users, :table_html => { :class => "table table-hover table-bordered" },
                      :sortable => true,
                      :sort_url => sort_admin_users_path,
                      :link_namespace => :admin,
                      :data_row_html => {
                        :class => lambda { cycle('success', 'error', 'warning', 'info')},
                        :id => lambda { |user| "user-#{user.id}" }} do |table| %>
  <% table.column :data => "Modify", :link_action => :edit %>
  <% table.column :data => "Show", :link_url => lambda { |user| admin_user_path(user) } %>
  <% table.column :data => "Show 2.0", :link => true %>
  <% table.column :email, :header => "Email Address" %>
  <% table.column :first_name, :formatter => :downcase %>
  <% table.column :last_name, :formatter => Proc.new { |last_name| last_name.upcase } %>
  <% table.column :created_at, :formatter => [:strftime, "%m/%d/%y %I:%M %p"] %>
  <% table.column :updated_at,
                  :header => Proc.new {
                    content_tag(:span, :class => "badge badge-success") do
                      "Last Updated"
                    end
                  },
                  :sortable => false,
                  :header_column_html => { :style => "background-color:orange" },
                  :data => Proc.new { time_ago_in_words table.current_row.updated_at } %>
  <% table.column :full_name, :header => "Full Name", :order => "last_name, first_name" do |user| %>
    <%= "#{user.first_name} #{user.last_name}" %>
  <% end %>
  <% table.header :full_name do |column, options| %>
    <%= table.header_sort_link(column, options) do %>
      <span class="label label-important">FULL NAME</span>
    <% end %>
  <% end %>
  <% table.column :data => "Delete", :link_method => :delete, :link_confirm => "Are you sure?" %>
  <% table.footer do %>
    <div class="pull-right">
      <%= will_paginate @users %>
    </div>
  <% end %>
<% end %>

Produces (with Twitter Bootstrap):

<img src=“https://raw.github.com/hunterae/table-for/master/example_table.png”>

For detailed instructions on how to run this example, along with comments on every line of the above table, check out the Example Details.

table_for options

The first argument to the table_for call will always be the array of domain objects. The second argument is a hash and is optional. It is any combination of the following options:

sortable

(defaults to false) Sets whether all columns are sortable by default. If this field is set to true, each column header will be generated as a link.

sort_url

(defaults to “”) Sets the url for the header column links. This will only affect columns that are sortable.

link_namespace

(defaults to nil) Sets the default namespace for any links generated in the columns. For example, a link_namespace of admin would try to build links within the admin namespace in the routes. This can be specified as a string, an array, a domain object, or a symbol, i.e. :link_namespace => [:admin, @post, :comments]

table_html

(defaults to nil) Hash to specify the styles, classes, id, and other attributes applied to the table element, i.e. :table_html => { :id => “my-table”, :class => “table table-bordered”, :cellpadding => 2 }.

thead_html

(defaults to nil) Hash to specify the styles, classes, id, and other attributes applied to the thead element, i.e. :thead_html => { :id => “thead-id” } Note: If TableFor.render_thead_element is set to false, the thead surrounding element for the header row will not be rendered.

header_row_html

(defaults to nil) Hash to specify the styles, classes, id, and other attributes applied to the header row (tr) element, i.e. :header_row_html => { :style => ‘color: orange’ }

header_column_html

(defaults to {}) Hash to specify the styles, classes, id, and other attributes applied to the header column (th) element. The values in this hash can each be a string or a Proc that takes (optionally) the column object as a parameter i.e. :header_column => { :style => “font-weight: bold” }, or :header_column => { :class => Proc.new {|column| “#{column.name}_header” } }

tbody_html

(defaults to nil) Hash to specify the styles, classes, id, and other attributes applied to the tbody element, i.e. :tbody_html => { :id => “body-id” } Note: If TableFor.render_tbody_element is set to false, the tbody surrounding element for the table data rows will not be rendered.

data_row_html

(defaults to nil) Hash to specify the styles, classes, id, and other attributes applied to each data row element (tr). The values in this hash can each be a string or a Proc that takes (optionally) the current record as a parameter i.e. :data_row_html => { :class => lambda { cycle(‘success’, ‘error’, ‘warning’, ‘info’)}, :id => lambda { |user| “user-#useruser.id” } }

data_column_html

(defaults to {}) Hash to specify the styles, classes, id, and other attributes applied to the header column (th) element. The values in this hash can each be a string or a Proc that takes (optionally) the current_record and (also optionally) the column object as parameters i.e. :data_column_html => { :style => “font-weight: bold”, :id => Proc.new {|record, column| “record-#{record.id}-#columncolumn.name” } }

tfoot_html

(defaults to nil) Hash to specify the styles, classes, id, and other attributes applied to the tfoot element, i.e. :tfoot_html => { :id => “tfoot-id” } Note: If TableFor.render_tfoot_element is set to false, the tfoot surrounding element for the footer row will not be rendered.

footer_row_html

(defaults to nil) Hash to specify the styles, classes, id, and other attributes applied to the footer row (tr) element, i.e. :footer_row_html => { :style => ‘color: orange’ }

footer_column_html

TODO

table_for column options

data

TODO

header

TODO

formatter

TODO

sortable

TODO

sort_url

TODO

order

TODO

link_url

TODO

link_action

TODO

link_method

TODO

link_confirm

TODO

link_html
link

TODO

data_column_html

TODO

header_column_html

TODO

table_for header options

TODO

table_for footer options

TODO

table_for configuration

TODO

Using “Before” and “After” hooks

TODO