TabulaRasa
An opinionated yet simple table generator for Rails1.
TabulaRasa is designed to leverage ActiveRecord::Relation instances and conventions to make table generation a snap but still readable and editable.
Installation
Add this line to your application's Gemfile:
gem 'tabula_rasa'
And then execute:
$ bundle
Or install it yourself as:
$ gem install tabula_rasa
Usage
TabulaRasa is designed to make it easy to make valid HTML[5] tables for ActiveRecord::Relations. Here are examples on how to set attributes:
# TABLE
# NOTE: special options here:
# * zebra: Accepts boolean or array of string values for ActionView's cycle helper. Defaults to true, creating zebra-striped tables (using 'even' and 'odd' values) out of the box.
# * dom_id: Accepts boolean, for setting TBODY TR id attribute to dom_id for the row's instance. Defaults to false.
# * dom_class: Accepts boolean, for adding dom_class for the row's instance to the TBODY TR class attribute. Defaults to false.
tabula_rasa @collection id: 'foo' do |table|
t.column :foo
end
# THEAD
tabula_rasa @collection, head: {id: 'foo'} do |table|
t.column :foo
end
# THEAD TR not supported. There's only one row. Use the THEAD TR selector instead.
# TH
tabula_rasa @collection do |table|
t.column :foo, head: {id: 'foo'}
# You can also set both TH and TD attributes with the same values
t.column :bar, shared: {class: 'bar'}
# NOTE: block column arguments are not supported for TH element
end
# TBODY
tabula_rasa @collection, body: {id: 'foo'} do |table|
t.column :foo
end
# TBODY TR
tabula_rasa @collection do |table|
t.column :foo # Just here for validity
# This is the code that actually does the work for the TR
t.row class: 'foobar'
# OR you can use a block argument. Do note though...
# Defining the row twice in real code will raise ArgumentError.
t.row do |row|
row.id do |instance|
dom_id instance
end
# Sets attribute 'data-foo'
row.data :foo do |instance|
"foo-#{instance.id}"
end
end
end
# TD
tabula_rasa @collection do |table|
t.column :foo, body: {class: 'foo'}
t.column :bar do |column|
column.class do |instance|
instance.bar? ? 'bar' : 'unbar'
end
# Just an example of another attribute where setting by string might make sense. Use CSS for this really!
column.attribute :width, '100'
end
# You can also set both TH and TD attributes with the same values
t.column :baz, shared: {class: 'baz'}
end
Cell values default to the attribute name [for the TH element] and value [for the TD element]. You can easily override this by using the :value key for the :head or :body options for the column method as seen below:
tabula_rasa @collection do |table|
t.column :foo, head: {value: 'Foo Header'}, body: {value: 'Foo Body Content'}
end
Most use cases for overriding the body value though would be better served by using a block which provides access to the collection member for that row.
tabula_rasa @collection do |table|
t.column :foo do |column|
column.value do |instance|
"A massaged value for instance #{instance.id}"
end
end
end
A lot of the time though you should just be able to get by with a simple symbol argument, since you aren't limited to simple attributes but can use methods that massage attribute data.
tabula_rasa @collection do |table|
t.column :foo
end
Contributing
- Fork it
- Create your feature branch (
git checkout -b my-new-feature
) - Commit your changes (
git commit -am 'Add some feature'
) - Push to the branch (
git push origin my-new-feature
) - Create new Pull Request
TODO
- Discover more things to do
Footnotes
1 TabulaRasa really only relies on ActiveRecord and ActionView/ActionPack so you could use in a non-Rails stack that had those two elements but it seemed silly to differentiate this in the summary sentence.