README.textile in tabulatr-0.0.5 vs README.textile in tabulatr-0.1.0
- old
+ new
@@ -6,42 +6,43 @@
We found ourselves reinventing the wheel in every project we made, by using
* different paging mechanisms,
* different ways of implementing filtering/searching,
-* difterent ways of implementing selecting and batch actions,
+* 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.
h3. Visual Components
Every Tabulatr table consists of the following components:
* a wrapping form
* a 'Controls Container' containing the table-controls as
- * the paginator,
- * the batch_actions,
- * the submit button,
- * controls to manage selecting/checking/marking,
- * an info_text
+** the paginator,
+** the batch_actions,
+** the submit button,
+** controls to manage selecting/checking/marking,
+** an info_text
* The actual table consisting of
- * A header row,
- * A filter row,
- * data rows,
- * possibly a selecting/checking/marking column
- * possibly action links/buttons
+** A header row,
+** A filter row,
+** data rows,
+** possibly a selecting/checking/marking column
+** possibly action links/buttons
Whilst this is a strong decision, we made everything as-configurable-as-possible, there are roughly 150 options you can use to tweak almost every aspect of Tabulatr.
h3. Features
Tabulatr tries to make these common tasks as simple/transparent as possible:
* paging
* selecting/checking/marking
* filtering
* batch actions
+* stateful index pages
h2. Example
h3. Models
@@ -58,11 +59,11 @@
def index
@products = Product.find_for_table(params)
end
</pre>
-the find_for_table method is injected into ActiveRecord by Tabulatr, it retrieves all relevant data from the params hash automagically.
+the <tt>find_for_table</tt> method is injected into ActiveRecord by Tabulatr, it retrieves all relevant data from the <tt>params</tt> hash automagically. If you want the the table to be stateful, i.e. remembering its sorting/filtering/selecting settings (very useful when processing a certain selection of entries), you can pass the option <tt>:stateful => session</tt> to the <tt>find_for_table</tt> call and the data will be stored. Also, a _Reset_ button will be rendered to get rid of the state.
h3. View
To get a simple Table, all we need to do is
@@ -103,12 +104,14 @@
<%= table_for @products, :batch_actions => {'foo' => 'Foo', 'delete' => "Delete"} do |t|
...
end %>
</pre>
-to handle the actual batch action, we have to add a block to the <tt>find_for_table</tt> call in the controller:
+If you prefer individual buttons for the batch actions over a select input, give the option <tt>:batch_actions_type => :button</tt> to the <tt>table_for</tt> call.
+To handle the actual batch action, we have to add a block to the <tt>find_for_table</tt> call in the controller:
+
<pre>
@products = Product.find_for_table(params) do |batch_actions|
batch_actions.delete do |ids|
ids.each do |id|
Product.find(id).destroy
@@ -199,10 +202,11 @@
select_none_label: 'Select None', # Text on the select none button
select_visible_label: 'Select visible', # Text on the select visible button
unselect_visible_label: 'Unselect visible', # Text on the unselect visible button
select_filtered_label: 'Select filtered', # Text on the select filtered button
unselect_filtered_label: 'Unselect filtered', # Text on the unselect filtered button
+ reset_label: 'Reset', # Text on the reset button
info_text: "Showing %1$d, total %2$d, selected %3$d, matching %4$d",
# which controls to be rendered above and below the tabel and in which order
before_table_controls: [:submit, :paginator, :batch_actions, :select_controls, :info_text],
after_table_controls: [],
@@ -311,10 +315,10 @@
* <a href="http://github.com/provideal/id_stuffer">IdStuffer</a> to compress the _remembered_ ids.
* And... eh... It's an extension for Rails 3, so it might be handy to have a version of Rails 3 and Ruby 1.8.? or 1.9.?.
h2. Bugs
-There are, definitely, roughly 1000 bugs in Tabulatr, although we do some testing (see <tt>spec/</tt>). So if you hunt them, please let me know.
+There are, definitely, roughly 999 bugs in Tabulatr, although we do some testing (see <tt>spec/</tt>). So if you hunt them, please let me know using the <a href="https://github.com/provideal/tabulatr/issues">GitHub Bugtracker</a>.
h2. License
Copyright (c) 2010-2011 Peter Horn, <a href="http://www.provideal.net" target="_blank">Provideal GmbH</a>