Tabulatr2 - Index Tables made easy

Requirements

Ruby 2.0.0 or higher
Rails 4.0.0 or higher
Bootstrap from Twitter

Installation

Require tabulatr2 in your Gemfile:

gem 'tabulatr2'

After that run bundle install.

Also add //= require tabulatr to your application js file and *= require tabulatr to your CSS asset pipeline.

In order to get the provided i18n language files run rails g tabulatr:install

The DSL

Tabulatr provides an easy to use DSL to define the data to be used in your table. It is defined in TabulatrData classes. If you have a User model you would create a UserTabulatrData class.

class UserTabulatrData < Tabulatr::Data
end

Instead of creating this class by hand you can also generate a TabulatrData for a given class by running rails g tabulatr:table User

Columns

Let's say you want to display each user's first_name and last_name attribute:

class UserTabulatrData < Tabulatr::Data
  column :first_name
  column :last_name
end

That's it. It'll work, but let's assume you would like to display the full name in one single column. No worries! Tabulatr got you covered:

class UserTabulatrData < Tabulatr::Data
  column :full_name, table_column_options: {header: 'The full name'} do |user|
    link_to "#{user.first_name} #{user.last_name}", user
  end
end

As you can see you just need to provide a block to the column call and you can format the cell into whatever you want. You can even use all those fancy Rails helpers!

Unfortunately, we can't sort and filter this column right now because Tabulatr would look for a full_name column in your DB table but there is no such thing. Bummer! Enter sort_sql and filter_sql:

Sorting / Filtering

class UserTabulatrData < Tabulatr::Data
  column :full_name, sort_sql: "users.first_name || '' || users.last_name",
                   filter_sql: "users.first_name || '' || users.last_name"
end

With these two options you can provide whatever SQL you would like to have executed when filtering or sorting this particular column. If instead you want to disable sorting and filtering at all, you can do that too:

class UserTabulatrData < Tabulatr::Data
  column :full_name, table_column_options: {sortable: false, filter: false}
end

Also you are able to change generated filter form field for this column. Say for example you want to have an exact filter instead of a LIKE filter:

class UserTabulatrData < Tabulatr::Data
  column :first_name, table_column_options: {filter: :exact}
end

Following is a table with all the standard mappings for filter fields, which means these filters get created if you don't overwrite it:

Data type	Generated form field / SQL
integer, float, decimal	String input field, exact match
string, text	String input field, LIKE match
date, time, datetime, timestamp	Select field, with options like 'last 30 days', 'today', ...
boolean	Select field, options are 'Yes', 'No' and 'Both'

Associations

To display associations you would use the association method with the association name and the attribute on the association as it's first two arguments:

class UserTabulatrData < Tabulatr::Data
  association :citizenship, :name
end

Associations take the same arguments as the column method:

class UserTabulatrData < Tabulatr::Data
  association :citizenship, :name do
    record.citizenship.name.upcase
  end

  association :posts, :text, table_column_options: {filter: false, sortable: false} do |user|
    user.posts.count
  end
end

Checkbox

To provide a checkbox for each row which is needed by batch actions just call checkbox:

class UserTabulatrData < Tabulatr::Data
 checkbox
end

Search

The DSL provides you with a search method to define a custom fuzzy search method which is not bound to a specific column.

class UserTabulatrData < Tabulatr::Data
  search do |query|
   "users.first_name LIKE '#{query}' OR users.last_name LIKE '#{query}' OR users.address LIKE '#{query}'"
  end

  # This call could also be written as:
  # search :first_name, :last_name, :address
end

Row formatting

To provide row specific HTML-Attributes call row:

row do |record, row_config|
  if record.super_important?
    row_config[:class] = 'important';
  end
  row_config[:data] = {
    href: edit_user_path(record.id),
    vip: record.super_important?
  }
end

Usage

Great, we have defined all the required columns in the TabulatrData DSL, but how do we display the table now?

In UsersController#index we write:

  def index
    tabulatr_for User
  end

This call responds to an HTML-Request by rendering the associated view and for a JSON-Request by fetching the requested records.

Hint: If you want to prefilter your table, you can do that too! Just pass an ActiveRecord::Relation to tabulatr_for:

  def index
    tabulatr_for User.where(active: true)
  end

In the view we can use all the attributes which are defined in our UserTabulatrData class. To display all the columns defined in the UserTabulatrData class we just need to put the following statement in our view:

<%= table_for User %>

If you just want do display a subset of the defined columns or show them in a different order you can provide them as arguments to the columns key:

<%= table_for User, columns: [:full_name, 'citizenship:name', {posts: :text}]%>

Note that you can write associations as a string with colon between association name and method or as a hash as you can see above.

An other option is to provide the columns in a block:

  <%= table_for User do |t|
    t.column :full_name
    t.column :active
    t.association :citizenship, :name
    t.association :posts, :text
    t.column :edit_link
  end %>

To add a checkbox column just add

t.checkbox

To add a select box with batch-actions (actions that should be performed on all selected rows), we add an option to the table_for:

  <%= table_for User, batch_actions: {'foo' => 'Foo', 'delete' => "Delete"} do |t|
    ...
  end %>

To handle the actual batch action, we have to add a block to the tabulatr_for call in the controller:

  tabulatr_for User do |batch_actions|
    batch_actions.delete do |ids|
      ids.each do |id|
        User.find(id).destroy
      end
      redirect_to root_path()
      return
    end
    batch_actions.foo do |ids|
      ... do whatever is foo-ish to the records
    end
  end

where the ids parameter to the block is actually an Array containing the numeric ids of the currently selected rows.

Features

Tabulatr aims at making the ever-recurring task of creating listings of ActiveRecord models simple and uniform.

We found ourselves reinventing the wheel in every project we made, by using

different paging mechanisms,
different ways of implementing filtering/searching,
different ways of implementing selecting and batch actions,
different layouts.

We finally thought that whilst gems like Formtastic or SimpleForm provide a really cool, uniform and concise way to implement forms, it's time for a table builder. During a project with Magento, we decided that their general tables are quite reasonable, and enterprise-proven -- so that's our starting point.

Tabulatr tries to make these common tasks as simple/transparent as possible:

paging
selecting/checking/marking
filtering
batch actions

Options

Table Options

These options should be specified at the view level as parameters to the table_for call. They change the appearance and behaviour of the table.

  filter: true,          # false for no filter row at all
  search: true,          # show fuzzy search field
  paginate: false,       # true to show paginator
  pagesize: 20,          # default pagesize
  sortable: true,        # true to allow sorting (can be specified for every sortable column)
  batch_actions: false,  # :name => value hash of batch action stuff
  footer_content: false, # if given, add a <%= content_for <footer_content> %> before the </table>
  path: '#',             # where to send the AJAX-requests to
  order_by: nil          # default order,
  html_class: ''         # html classes for the table element

Example:

<%= table_for User, {order_by: 'last_name desc', pagesize: 50} %>

Column Options

You can specify these options either in your TabulatrData class or to the columns in the block of table_for.

  header: nil,           # override content of header cell
  classes: nil,          # CSS classes for this column
  width: false,
  align: false,
  valign: false,
  wrap: nil,
  th_html: false,
  filter_html: false,
  filter: true,          # whether this column should be filterable
  sortable: true,        # whethter this column should be sortable
  format: nil,
  map: true,
  cell_style: {},        # CSS style for all body cells of this column
  header_style: {}       # CSS style for all header cells of this column

Example:

# in the view
<%= table_for User do |t|
  t.column(:first_name, header_style: {color: 'red'})
  # ...
%>

# or in TabulatrData
class UserTabulatrData < Tabulatr::Data
  column(:first_name, table_column_options: {header_style: {color: 'red'}})
end

Contributing

Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
Check out the Issue tracker to make sure someone already hasn't requested it and/or contributed it
Fork the project
Start a feature/bugfix branch
Commit and push until you are happy with your contribution
Make sure to add tests for it, run them via rspec spec and check that they all pass.
Please try not to mess with the Rakefile, version, or history. If you want to have your own version, or is otherwise necessary, that is fine, but please isolate to its own commit so I can cherry-pick around it.
Feel free to send a pull request if you think others (me, for example) would like to have your change incorporated into future versions of tabulatr.

License

MIT

uu/tabulatr2

Tabulatr2 - Index Tables made easy

Requirements

Installation

The DSL

Columns

Sorting / Filtering

Associations

Checkbox

Search

Row formatting

Usage

Features

Options

Table Options

Example:

Column Options

Example:

Contributing

License