README.textile in tabulatr-0.0.1 vs README.textile in tabulatr-0.0.2
- old
+ new
@@ -9,30 +9,30 @@
* different paging mechanisms,
* different ways of implementing filtering/searching,
* difterent 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 (*shiver*) we decided that their general tables are quite reasonable, and enterprise-proven -- so that's our starting point.
+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 (*shiver*) 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,
+ * 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
-
+
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:
@@ -47,11 +47,11 @@
We suppose we have a couple of models
* tags has and belong to many products
* vendors have many products
* products belong to vendors and have and belong to many tags
-
+
h3. Controller
In the products controllers index action we have:
<pre>
@@ -60,11 +60,11 @@
end
</pre>
the find_for_table method is injected into ActiveRecord by Tabulatr, it retrieves all relevant data from the params hash automagically.
-h3.View
+h3. View
To get a simple Table, all we need to do is
<pre>
<%= table_for @products do |t|
@@ -77,92 +77,132 @@
end %>
</pre>
but the result is pretty fancy, already:
-<img src="assets/simple_table.png" />
+<img src="https://github.com/provideal/tabulatr/raw/master/assets/simple_table.png" />
To add a column with ckeckboxes (thus giving all the "Select ..." buttons a reasonable semantics), we simply add a
+
<pre>
- t.checkbox
+ t.checkbox
</pre>
+
row.
To add e.g. edit-buttons, we specify
+
<pre>
t.action do |record|
link_to "Edit", edit_product_path(record)
end
</pre>
To add a select-popup with batch-actions (i.e., actions that are to be perfored on all selected rows), we add an option to the table_for:
+
<pre>
<%= 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:
+
<pre>
@products = Product.find_for_table(params) do |batch_actions|
batch_actions.delete do |ids|
ids.each do |id|
Product.find(id).destroy
end
redirect_to index_select_products_path()
return
end
batch_actions.foo do |ids|
- # do whatever is foo-ish to the records
+ ... do whatever is foo-ish to the records
end
end
</pre>
+
where the <tt>ids</tt> parameter to the block is actually an Array containing the numeric ids of the currently selected rows.
+h2. Installation
+
+Installation is pretty straightforward. Just include a line
+
+<pre>
+ gem 'tabulatr', '...current version here'
+</pre>
+
+in your applications <tt>Gemfile</tt>, then run <tt>bundle install</tt>.
+
+If you want to use a predefined stylesheet and the images for sorting and paging, just issue
+
+<pre>
+ $ rails g tabulatr:install
+ create public/stylesheets/tabulatr.css
+ create public/images/tabulatr/buttons_lite_background.png
+ create public/images/tabulatr/pager_arrow_left.gif
+ create public/images/tabulatr/pager_arrow_left_off.gif
+ create public/images/tabulatr/pager_arrow_right.gif
+ create public/images/tabulatr/pager_arrow_right_off.gif
+ create public/images/tabulatr/sort_arrow_down.gif
+ create public/images/tabulatr/sort_arrow_down_off.gif
+ create public/images/tabulatr/sort_arrow_up.gif
+ create public/images/tabulatr/sort_arrow_up_off.gif
+ -------------------------------------------------------
+ Please note: We have copied a sample stylesheet to
+ public/stylesheets/tabulatr.css
+ to actually use it in your application, please include
+ it in your layout file. You may use s/th like
+ <%= stylesheet_link_tag :tabulatr %>
+ for that.
+ -------------------------------------------------------
+</pre>
+
h2. Options
Literally every aspect of Tabulatr can be tweaked to fit your needs. You may add or remove components, change the class or other html attributes of the generated html nodes. There are options of several types:
h3. Table Options
These options are to be specified at the form_for level and change the appearance and behaviour of the table. This is taken from <tt>lib/tabulatr/tabulatr/settings.rb</tt>
<pre>
- remote: false, # add data-remote="true" to form
- form_class: 'tabulatr_form', # class of the overall form
- table_class: 'tabulatr_table', # class for the actual data table
- sortable_class: 'sortable', # class for the header of a sortable column
- sorting_asc_class: 'sorting-asc', # class for the currently asc sorting column
- sorting_desc_class: 'sorting-desc', # class for the currently desc sorting column
- page_left_class: 'page-left', # class for the page left button
- page_right_class: 'page-right', # class for the page right button
- page_no_class: 'page-no', # class for the page no <input>
- control_div_class_before: 'table-controls', # class of the upper div containing the paging and batch action controls
- control_div_class_after: 'table-controls', # class of the lower div containing the paging and batch action controls
- paginator_div_class: 'paginator', # class of the div containing the paging controls
- batch_actions_div_class: 'batch-actions', # class of the div containing the batch action controls
+ remote: false, # add data-remote="true" to form
+ form_class: 'tabulatr_form', # class of the overall form
+ table_class: 'tabulatr_table', # class for the actual data table
+ sortable_class: 'sortable', # class for the header of a sortable column
+ sorting_asc_class: 'sorting-asc', # class for the currently asc sorting column
+ sorting_desc_class: 'sorting-desc', # class for the currently desc sorting column
+ page_left_class: 'page-left', # class for the page left button
+ page_right_class: 'page-right', # class for the page right button
+ page_no_class: 'page-no', # class for the page no <input>
+ control_div_class_before: 'table-controls', # class of the upper div containing the paging and batch action controls
+ control_div_class_after: 'table-controls', # class of the lower div containing the paging and batch action controls
+ paginator_div_class: 'paginator', # class of the div containing the paging controls
+ batch_actions_div_class: 'batch-actions', # class of the div containing the batch action controls
select_controls_div_class: 'check-controls', # class of the div containing the check controls
- submit_class: 'submit-table', # class of submit button
- pagesize_select_class: 'pagesize_select', # class of the pagesize select element
- select_all_class: 'select-btn', # class of the select all button
- select_none_class: 'select-btn', # class of the select none button
- select_visible_class: 'select-btn', # class of the select visible button
- unselect_visible_class: 'select-btn', # class of the unselect visible button
- select_filtered_class: 'select-btn', # class of the select filtered button
- unselect_filtered_class: 'select-btn', # class of the unselect filteredbutton
- info_text_class: 'info-text', # class of the info text div
+ submit_class: 'submit-table', # class of submit button
+ pagesize_select_class: 'pagesize_select', # class of the pagesize select element
+ select_all_class: 'select-btn', # class of the select all button
+ select_none_class: 'select-btn', # class of the select none button
+ select_visible_class: 'select-btn', # class of the select visible button
+ unselect_visible_class: 'select-btn', # class of the unselect visible button
+ select_filtered_class: 'select-btn', # class of the select filtered button
+ unselect_filtered_class: 'select-btn', # class of the unselect filteredbutton
+ info_text_class: 'info-text', # class of the info text div
- batch_actions_label: 'Batch Action: ', # Text to show in front of the batch action select
- batch_actions_type: :select, # :select or :button depending on the kind of input you want
- batch_actions_class: 'batch-action-inputs', # class to apply on the batch action input elements
- submit_label: 'Apply', # Text on the submit button
- select_all_label: 'Select All', # Text on the select all button
- 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
+ batch_actions_label: 'Batch Action: ', # Text to show in front of the batch action select
+ batch_actions_type: :select, # :select or :button depending on the kind of input you want
+ batch_actions_class: 'batch-action-inputs', # class to apply on the batch action input elements
+ submit_label: 'Apply', # Text on the submit button
+ select_all_label: 'Select All', # Text on the select all button
+ 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
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: [],
@@ -206,11 +246,10 @@
wrap: true, # wraps
type: :string, # :integer, :date
td_html: false, # a hash with html attributes for the cells
th_html: false, # a hash with html attributes for the header cell
filter_html: false, # a hash with html attributes for the filter cell
- filter_html: false, # a hash with html attributes for the filter cell
filter: true, # false for no filter field,
# container for options_for_select
# String from options_from_collection_for_select or the like
# :range for range spec
# :checkbox for a 0/1 valued checkbox
@@ -223,17 +262,18 @@
link: false, # proc or symbol to make the content a link
join_symbol: ', ', # symbol used to join the elements of 'many' associations
sortable: true # if set, sorting-stuff is added to the header cell
</pre>
-h3. Global settings
+h3. Global settings
These settings are *not* supposed to be changed on a per-table basis. This is necessary, because the <tt>find_for_table</tt> method needs to rely on a priori information.
h4. Table Form Options
-This hash contains all the information about the naming of the generated form elements. To override them, you should, in an initializer, call
+This hash contains all the information about the naming of the generated form elements. To override them, you should, in an initializer, call
+
<pre>
Tabulatr.table_form_options(my_options_hash)
</pre>
<pre>
@@ -249,30 +289,31 @@
checked_separator: ',' # symbol to separate the checked ids
</pre>
h4. Paginate options
-To override these, you should, in an initializer, call
+To override these, you should, in an initializer, call
+
<pre>
Tabulatr.paginate_options(my_options_hash)
</pre>
<pre>
page: 1,
pagesize: 10,
pagesizes: [10, 20, 50]
</pre>
-h2.Dependencies
+h2. Dependencies
We use
-* <a href="http://github.com/providel/whiny_hash">WhinyHash</a> to handle the options in a fail-early-manner,
-* <a href="http://github.com/providel/id_stuffer">IdStuffer</a> to compress the _remembered_ ids.
-* And... eh... It's an extension for rails, so it might be handy to have a version of rails 3 and ruby 1.9.
+* <a href="http://github.com/provideal/whiny_hash">WhinyHash</a> to handle the options in a fail-early-manner,
+* <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.9.2.
-h2.Bugs
+h2. Bugs
-There are, definitely, roughly 1000 bugs in Tabulatr, although we do some testing (see <tt>spec/dummy_app/spec</tt>). So if you hunt them, please let me know.
+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.
h2. License
Copyright (c) 2010-2011 Peter Horn, <a href="http://www.provideal.net" target="_blank">Provideal GmbH</a>