Tableficate

A DSL for easy table creation with sorting and filtering. It tries to do to tables what simple_form and formtastic have done for forms. Below you'll find basic documentation with more compelete docs in the wiki.

This project follows Semantic Versioning.

Installation

$ gem install tableficate

If you're using Bundler, add this to your Gemfile:

gem 'tableficate', '~>0.2.0'

Support

Ruby

1.9+

Rails

3.1+

Templating

Any templating engine can be used. The default theme uses ERB.

Database Framework

ActiveRecord

Pagination

Any pagination can be used. The default theme has built-in support for Kaminari and will_paginate.

Basic Usage

Let's say that we want to create a table that lists active accounts in the system with their time of creation and the name on the account.

Our controller:

@accounts = Accounts.active.tableficate(params[:accounts]).page(params.try(:[], :accounts_page) || 1)

Here we're getting active accounts, calling tableficate and then paginating with Kaminari. Tableficate works on Arel objects and passes out an Arel so you can add things like pagination. We pass in the params for the table we'll create in the view. By default :accounts is derived from the database table name of the primary table in the query.

Our View:

<%= table_for @accounts, show_sorts: true do |t| %>
  <% t.column :id, header: 'Account Number' %>
  <% t.column :created_at do |account| %>
    <%= account.created_at.strftime('%m/%d/%Y') %>
  <% end %>
  <% t.column :first_name %>
  <% t.column :last_name %>
  <% t.actions do |account| %>
    <%= link_to('View', account_path(account)) %>
  <% end %>

  <% t.filter :first_name %>
  <% t.filter :last_name %>
<% end %>

This creates a sortable table with 2 filters, 4 data columns and a column for actions. Column headers are automatically generated but can be overridden as seen on :id. The column output can also be overridden by passing a block to the call. This setup only covers basic functionality. Some of the more advanced functionality requires you to wrap your scope in a special table model.

Having created the basic table we now want to default the sorting to show newest accounts first and we want :first_name and :last_name to be merged into one column. First, create a table model.

In "app/tables/" we'll create a new table model using the generator. Provide the name of the new table model and then the model being wrapped.

$ rails generate tableficate:table AccountReport Account

Our table model:

class AccountReport < Tableficate::Base
  scope :account

  default_sort :created_at, 'DESC'

  column :full_name, sort: 'first_name ASC, last_name ASC'

  filter :full_name do |value, scope|
    first_name, last_name = value.split(/\s+/)

    if last_name.nil?
      scope.where(['first_name LIKE ? OR last_name LIKE ?', first_name, first_name])
    else
      scope.where(['first_name LIKE ? AND last_name LIKE ?', first_name, last_name])
    end 
  end
end

We've defined a scope that we're wrapping. Then we provide a default sorting and explain how to sort and filter a new column called :full_name.

Our new controller using AccountReport:

@accounts = AccountReport.active.tableficate(params[:accounts]).page(params.try(:[], :accounts_page) || 1)

Our new view using :full_name:

<%= table_for @accounts, show_sorts: true do |t| %>
  <% t.column :id, header: 'Account Number' %>
  <% t.column :created_at do |account| %>
    <%= account.created_at.strftime('%m/%d/%Y') %>
  <% end %>
  <% t.column :full_name do |account| %>
    <%= "#{account.first_name} #{account.last_name}" %>
  <% end %>
  <% t.actions do |account| %>
    <%= link_to('View', account_path(account)) %>
  <% end %>

  <% t.filter :full_name %>
<% end %>

Now we have default sorting, sortable columns and a full name filter.

Themes

New themes can be created using the theme generator.

$ rails generate tableficate:theme foo

The theme can then be applied to a table.

<%= table_for @records, theme: 'foo' do |t| %>
  ...
<% end %>

Changes Needed to Upgrade From 0.1

  1. The filter functions used in the table_for call have been completely changed. They will need to be rewritten in all of your calls.
  2. New filter partials have been added to accomodate the new filter types that are available. If you have custom themes they will need to be updated. This can be done by first moving "_column_header.html.erb" to "_header.html.erb", "filters/_input_field.html.erb" to "filters/_input.html.erb" and "filters/_input_field_range.html.erb" to "filters/_input_range.html.erb". Then rerun rails generate tableficate:theme NAME. This will not overwrite files you have altered for your new theme.