tabulatr2 0.9.4 → 0.9.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 0b11a5d5bda9718541550adc016fca03765e3e06
-  data.tar.gz: 5281e726afe6e44bec05af2a31d72e3546201180
+  metadata.gz: 12605d45404e6136d56147d684e8715ec17a46f8
+  data.tar.gz: deb114fca5a54182dfeed8aa02b5f0682267ffb2
 SHA512:
-  metadata.gz: 1cb47ebf2433da0db9280acb652d833fd4311629d111b03b175ff94ca3e695249222ce841dc7ba94e9e881ac935ebdb095aa1eaf2884670e93ce6284d95596e7
-  data.tar.gz: 231823bbb5a39e6f95c0991d3debab968f978d9a8ae8fe07203b9266eacb5f9ff729fa8ce9da26fcffd04ecfa7b93f2f5b5d828369c60e63ba8105d50586e5bb
+  metadata.gz: b537a626a5255ddb5c513d97c0f651dc99d34345dfda453fd41f9027e00b27972d54d23e477b27021dfad00614cae5c528a5a085994cd042059646f280e77dd4
+  data.tar.gz: cf74ff7bc31929f92e5bff94f6779c6e744d6364aa4fb09bff0332a6e1aa1b65bbe7426d5c405f95b7d790c4360d65626af1ddca8c6e22790e2c608687c23330

data/CHANGELOG.md

@@ -1,3 +1,32 @@
+## 0.9.6
+ * Adds localStorage persistency for tables. It's automatically turned on for paginated
+   tables and you can adjust the setting in your template.
+
+   Example:
+   ```
+   table_for Product, persistent: false
+   ```
+
+ * Added `font-awesome-rails`
+
+ * The DSL now accepts a search block with two block variables. The
+   second being the relation. The block needs to return an ActiveRecord::Relation,
+   a Hash, a String, nil or an Array.
+
+   Example:
+   ```ruby
+   search do |query, relation|
+    relation.joins(:vendor).where(["vendors.name = ?", query])
+   end
+   ```
+
+## 0.9.5
+ * Better DOM scopes to enable working with multiple tables per page
+ * Added `pagination_position` option to `table_for`.
+   Possible values are `:top`, `:bottom` and `:both`.
+ * Add 'mark all' checkbox in header row again
+ * Added `html_class` option to `table_for`
+
 ## 0.9.4
 
  * Fixed date filters

data/Gemfile

@@ -3,7 +3,6 @@ source 'https://rubygems.org'
 gemspec
 
 gem 'jquery-rails'
-gem 'slim'
 
 group :development do
   gem 'better_errors'
@@ -19,6 +18,6 @@ group :development, :test do
   gem 'launchy'
   gem 'database_cleaner', '< 1.1.0'
   gem 'poltergeist'
-  gem 'sass-rails', '~> 4.0.0'
+  gem 'sass-rails', '~> 4.0.0', '>= 4.0.2'
   gem 'bootstrap-sass', '~> 3.0.3.0'
 end

data/README.md

@@ -3,6 +3,12 @@
 [![Code Climate](https://codeclimate.com/github/provideal/tabulatr2.png)](https://codeclimate.com/github/provideal/tabulatr2)
 [![Travis CI](https://api.travis-ci.org/provideal/tabulatr2.png)](https://travis-ci.org/provideal/tabulatr2)
 
+## Requirements
+
+* Ruby 2.0.0 or higher
+* Rails 4.0.0 or higher
+* [Bootstrap from Twitter](http://getbootstrap.com)
+
 ## Installation
 
 Require tabulatr2 in your Gemfile:
@@ -14,103 +20,186 @@ After that run `bundle install`.
 Also add `//= require tabulatr` to your application js file and `*= require tabulatr` to your CSS asset
 pipeline.
 
-Now run the Install generator via
-`rails g tabulatr install`
+In order to get the provided `i18n` language files run
+`rails g tabulatr:install`
 
-## Usage
+## The DSL
 
-### Models
+`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.
 
-We suppose we have these three models:
 ```ruby
-class Tag < ActiveRecord::Base
-  has_and_belongs_to_many :products
+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:
+
 ```ruby
-class Product < ActiveRecord::Base
-  belongs_to :vendor
-  has_and_belongs_to_many :tags
+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:
+
+```ruby
+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
+
 ```ruby
-class Vendor < ActiveRecord::Base
-  has_many :products
+class UserTabulatrData < Tabulatr::Data
+  column :full_name, sort_sql: "users.first_name || '' || users.last_name",
+                   filter_sql: "users.first_name || '' || users.last_name"
 end
 ```
 
-and we want to display information about products in the `ProductsController#index` action.
+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:
 
-## ProductTabulatrData
+```ruby
+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:
 
-In this class we define which information should be available for the table and how it is formatted.
 ```ruby
-class ProductTabulatrData < Tabulatr::Data
+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'
 
-  search :vendor_address, :title
 
-  # search do |query|
-  #   "products.title LIKE '#{query}'"
-  # end
+### Associations
 
-  column :id
-  column :title { title.capitalize }
-  column :price do "#{price} EUR" end
-  column :vendor_address, sort_sql: "vendors.zipcode || '' || vendors.city",
-                        filter_sql: "vendors.street || '' || vendors.zipcode || '' vendors.city" do
-         "#{vendor.house_number} #{vendor.street}, #{vendor.zipcode} #{vendor.city}"
+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:
+
+```ruby
+class UserTabulatrData < Tabulatr::Data
+  association :citizenship, :name
+end
+```
+
+Associations take the same arguments as the `column` method:
+
+```ruby
+class UserTabulatrData < Tabulatr::Data
+  association :citizenship, :name do
+    record.citizenship.name.upcase
   end
-  column :edit_link do
-    link_to "edit #{title}", product_path(id)
+
+  association :posts, :text, table_column_options: {filter: false, sortable: false} do |user|
+    user.posts.count
   end
-  column :updated_at do
-    "#{updated_at.strftime('%H:%M %Y/%m/%d')}"
+end
+```
+
+### Checkbox
+
+To provide a checkbox for each row which is needed by batch actions just call `checkbox`:
+
+```ruby
+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.
+
+```ruby
+class UserTabulatrData < Tabulatr::Data
+  search do |query|
+   "users.first_name LIKE '#{query}' OR users.last_name LIKE '#{query}' OR users.address LIKE '#{query}'"
   end
-  association :vendor, :name
-  association :tags, :title do "'#{tags.map(&:title).map(&:upcase).join(', ')}'" end
 
+  # This call could also be written as:
+  # search :first_name, :last_name, :address
 end
 ```
-The search method is used for a fuzzy search field.
 
-You can automatically generate a new TabulatrData-Class by running
-`rails g tabulatr:table MODELNAME`.
+### Row formatting
 
-This will generate a `MODELNAMETabulatrData` class in `app/tabulatr_data/MODELNAME_data.rb` for you.
+To provide row specific HTML-Attributes call `row`:
 
-This generator also gets executed if you just run the standard Rails `resource` generator.
+```ruby
+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
 
-## Controller
+Great, we have defined all the required `columns` in the TabulatrData DSL, but how do we display the table now?
 
-In `ProductsController#index` we have:
+In `UsersController#index` we write:
 
 ```ruby
   def index
-    tabulatr_for Product
+    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`:
 ```ruby
   def index
-    tabulatr_for Product.where(active: true)
+    tabulatr_for User.where(active: true)
   end
 ```
 
-### View
-
-In the view we can use all the attributes which are defined in our `ProductTabulatrData` class.
-To display all the columns defined in the `ProductTabulatrData` class we
+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:
 
 ```erb
-<%= table_for Product %>
+<%= 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:
 
 ```erb
-<%= table_for Product, columns: [:vendor_address, 'vendor:name', {tags: :title}]%>
+<%= 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.
@@ -118,13 +207,11 @@ name and method or as a hash as you can see above.
 An other option is to provide the columns in a block:
 
 ```erb
-  <%= table_for Product do |t|
-    t.column :title
-    t.column :price
-    t.association :vendor, :name
-    t.column :vendor_address
-    t.column :updated_at
-    t.association :tags, :title
+  <%= 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 %>
 ```
@@ -138,20 +225,20 @@ To add a select box with batch-actions (actions that should be performed on all
 we add an option to the table_for:
 
 ```erb
-  <%= table_for Product, batch_actions: {'foo' => 'Foo', 'delete' => "Delete"} do |t|
+  <%= 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 `find_for_table` call in the controller:
+To handle the actual batch action, we have to add a block to the `tabulatr_for` call in the controller:
 
 ```ruby
-  tabulatr_for Product do |batch_actions|
+  tabulatr_for User do |batch_actions|
     batch_actions.delete do |ids|
       ids.each do |id|
-        Product.find(id).destroy
+        User.find(id).destroy
       end
-      redirect_to index_select_products_path()
+      redirect_to root_path()
       return
     end
     batch_actions.foo do |ids|
@@ -203,12 +290,13 @@ They change the appearance and behaviour of the table.
   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
+  order_by: nil          # default order,
+  html_class: ''         # html classes for the table element
 ```
 
 #### Example:
 ```erb
-<%= table_for Product, {order_by: 'price desc', pagesize: 50} %>
+<%= table_for User, {order_by: 'last_name desc', pagesize: 50} %>
 ```
 
 ### Column Options
@@ -236,30 +324,17 @@ the columns in the block of `table_for`.
 #### Example:
 ```erb
 # in the view
-<%= table_for Product do |t|
-  t.column(:title, header_style: {color: 'red'})
+<%= table_for User do |t|
+  t.column(:first_name, header_style: {color: 'red'})
   # ...
 %>
 
 # or in TabulatrData
-class ProductTabulatrData < Tabulatr::Data
-  column(:title, table_column_options: {header_style: {color: 'red'}})
+class UserTabulatrData < Tabulatr::Data
+  column(:first_name, table_column_options: {header_style: {color: 'red'}})
 end
 ```
 
-## Dependencies
-
-We use [Bootstrap from Twitter](http://getbootstrap.com) in order to make the table look pretty decent.
-
-## Known Bugs
-
-### Request-URI Too Large error
-
-This is a problem particulary when using WEBrick, because WEBricks URIs must not exceed 2048 characters.
-And this limit is hard-coded IIRC. So – If you run into this limitation –
-please consider using another server.
-(Thanks to [stepheneb](https://github.com/stepheneb) for calling my attention back to this.)
-
 ## Contributing
 
 * Check out the latest master to make sure the feature hasn't been implemented or the bug hasn't been fixed yet
@@ -274,21 +349,6 @@ please consider using another server.
 * 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.
 
-## MIT License
-
-Copyright (c) 2010-2013 Peter Horn, Provideal GmbH</a>
-
-Permission is hereby granted, free of charge, to any person obtaining a copy of this software
-and associated documentation files (the "Software"), to deal in the Software without restriction,
-including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense,
-and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so,
-subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all copies or substantial
-portions of the Software.
+## License
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
-INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE
-AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
-DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT
-OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+[MIT](LICENSE)

data/app/assets/javascripts/tabulatr/_storage.js

@@ -0,0 +1,41 @@
+$(function(){
+  Tabulatr.prototype.retrieveTableFromLocalStorage = function(response){
+    var currentStorage = JSON.parse(localStorage[this.id]);
+    if(currentStorage !== undefined){
+      $('.pagination[data-table='+ this.id +'] a[data-page='+ response.meta.page +']'); 
+      var $table = $('#' + this.id);
+      var tableName = this.id.split('_')[0];
+      if(currentStorage[tableName +'_sort'] != ''){
+        var sortParam = currentStorage[tableName +'_sort'];
+        var header = $table.find('th.tabulatr-sortable[data-tabulatr-column-name="'+ sortParam.split(' ')[0] +'"]');
+        header.attr('data-sorted', sortParam.split(' ')[1]);
+        header.addClass('sorted');
+        $('.tabulatr_filter_form[data-table='+ this.id +'] input[name="'+ tableName +'_sort"]').val(sortParam);
+      }
+      $('input#'+ this.id +'_fuzzy_search_query').val(currentStorage[tableName +'_search']);
+      var objKeys = Object.keys(currentStorage);
+      var elem, formParent;
+      for(var i = 0; i < objKeys.length; i++){
+        elem = $('[name="'+ objKeys[i] +'"]');
+        if(elem.length > 0){
+          elem.val(currentStorage[objKeys[i]]);
+          formParent = elem.parents('.form-group[data-filter-column-name]');
+          if(formParent.length > 0){
+            formParent.show();
+            formParent.siblings('[data-filter-column-name="_submit"]').show();
+          }
+        }
+      }
+    }
+  };
+
+  Tabulatr.prototype.resetTable = function(){
+    tableName = this.id.split('_')[0];
+    localStorage.removeItem(this.id);
+    $('table#'+ this.id).find('th.sorted').removeClass('sorted').removeAttr('data-sorted');
+    $('form[data-table='+ this.id +'] input.search').val('');
+    $('[data-table-id="'+ this.id +'"] [data-filter-column-name]').hide().find('input[type=text], input[type=hidden], select').val('');
+    $('.tabulatr_filter_form[data-table='+ this.id +'] input[name="'+ tableName +'_sort"]').val('');
+    this.updateTable({page: 1}, true);
+  };
+});