fancygrid 1.1.0 → 2.0.0

data/CHANGELOG

@@ -1,3 +1,10 @@
+2.0.0 - Completely refactored version of fancygrid
+      - Better integration in to rails
+      - improved fancygrid setup process, less complicated
+      - added possibility to implement different ORMs
+      - added possibility to use builder and value formatter
+      - added "download" feature e.g. to download data in csv, json or xml format
+      - improved rails 3.2 asset pipeline compatibility
 1.0.0 - Added the "ajax_type" option so ajax callbacks are not restricted to GET requests only.
       - Fixed a js bug that removes the input field focus when doing a simple search
       BREAKING CHANGES:
@@ -7,8 +14,8 @@
           - Added new style
           - Every "js-" prefix in css classes is now "fg-" and stands for 'fancygrid'
 0.6.2 - Drop down select box is now possible as a simple search input field
-0.6.1 - Refactored js and improved column sorting
-0.6.0 - Initial implemetation of column sorting feature
+0.6.1 - Refactored js and improved leaf sorting
+0.6.0 - Initial implemetation of leaf sorting feature
 0.5.1 - Fixed the complex search and improved viewstate caching.
 0.5.0 - Initial implementation of the complex search.
 0.4.2 - Ability to define a block for print out a custom css class for each table row. Check out the 'css_proc' method

data/Gemfile

@@ -1,15 +1,12 @@
 source "http://rubygems.org"
 
-group :development do
-  gem "rails", ">=3.0.3"
-  gem "jeweler"
-end
+gem "rails"
+gem "haml"
+  
+group :development, :test do
 
-group :test do
-  gem "capybara", ">= 0.4.0"
-  gem "webrat"
   gem "sqlite3"
-  gem "rspec-rails", ">= 2.0.0.beta"
+  gem "rspec-rails"  
+  gem "jeweler"
 end
 
-

data/Gemfile.lock

@@ -1,125 +1,110 @@
 GEM
   remote: http://rubygems.org/
   specs:
-    abstract (1.0.0)
-    actionmailer (3.0.3)
-      actionpack (= 3.0.3)
-      mail (~> 2.2.9)
-    actionpack (3.0.3)
-      activemodel (= 3.0.3)
-      activesupport (= 3.0.3)
-      builder (~> 2.1.2)
-      erubis (~> 2.6.6)
-      i18n (~> 0.4)
-      rack (~> 1.2.1)
-      rack-mount (~> 0.6.13)
-      rack-test (~> 0.5.6)
-      tzinfo (~> 0.3.23)
-    activemodel (3.0.3)
-      activesupport (= 3.0.3)
-      builder (~> 2.1.2)
-      i18n (~> 0.4)
-    activerecord (3.0.3)
-      activemodel (= 3.0.3)
-      activesupport (= 3.0.3)
-      arel (~> 2.0.2)
-      tzinfo (~> 0.3.23)
-    activeresource (3.0.3)
-      activemodel (= 3.0.3)
-      activesupport (= 3.0.3)
-    activesupport (3.0.3)
-    arel (2.0.7)
-    builder (2.1.2)
-    capybara (0.4.1.1)
-      celerity (>= 0.7.9)
-      culerity (>= 0.2.4)
-      mime-types (>= 1.16)
-      nokogiri (>= 1.3.3)
-      rack (>= 1.0.0)
-      rack-test (>= 0.5.4)
-      selenium-webdriver (>= 0.0.27)
-      xpath (~> 0.1.3)
-    celerity (0.8.7)
-    childprocess (0.1.6)
-      ffi (~> 0.6.3)
-    culerity (0.2.15)
-    diff-lcs (1.1.2)
-    erubis (2.6.6)
-      abstract (>= 1.0.0)
-    ffi (0.6.3)
-      rake (>= 0.8.7)
+    actionmailer (3.2.0)
+      actionpack (= 3.2.0)
+      mail (~> 2.4.0)
+    actionpack (3.2.0)
+      activemodel (= 3.2.0)
+      activesupport (= 3.2.0)
+      builder (~> 3.0.0)
+      erubis (~> 2.7.0)
+      journey (~> 1.0.0)
+      rack (~> 1.4.0)
+      rack-cache (~> 1.1)
+      rack-test (~> 0.6.1)
+      sprockets (~> 2.1.2)
+    activemodel (3.2.0)
+      activesupport (= 3.2.0)
+      builder (~> 3.0.0)
+    activerecord (3.2.0)
+      activemodel (= 3.2.0)
+      activesupport (= 3.2.0)
+      arel (~> 3.0.0)
+      tzinfo (~> 0.3.29)
+    activeresource (3.2.0)
+      activemodel (= 3.2.0)
+      activesupport (= 3.2.0)
+    activesupport (3.2.0)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    arel (3.0.2)
+    builder (3.0.0)
+    diff-lcs (1.1.3)
+    erubis (2.7.0)
     git (1.2.5)
-    i18n (0.5.0)
-    jeweler (1.5.2)
-      bundler (~> 1.0.0)
+    haml (3.1.4)
+    hike (1.2.1)
+    i18n (0.6.0)
+    jeweler (1.6.4)
+      bundler (~> 1.0)
       git (>= 1.2.5)
       rake
-    json_pure (1.5.1)
-    mail (2.2.15)
-      activesupport (>= 2.3.6)
+    journey (1.0.3)
+    json (1.6.5)
+    mail (2.4.1)
       i18n (>= 0.4.0)
       mime-types (~> 1.16)
       treetop (~> 1.4.8)
-    mime-types (1.16)
-    nokogiri (1.4.4)
-    polyglot (0.3.1)
-    rack (1.2.1)
-    rack-mount (0.6.13)
-      rack (>= 1.0.0)
-    rack-test (0.5.7)
+    mime-types (1.17.2)
+    multi_json (1.1.0)
+    polyglot (0.3.3)
+    rack (1.4.1)
+    rack-cache (1.1)
+      rack (>= 0.4)
+    rack-ssl (1.3.2)
+      rack
+    rack-test (0.6.1)
       rack (>= 1.0)
-    rails (3.0.3)
-      actionmailer (= 3.0.3)
-      actionpack (= 3.0.3)
-      activerecord (= 3.0.3)
-      activeresource (= 3.0.3)
-      activesupport (= 3.0.3)
+    rails (3.2.0)
+      actionmailer (= 3.2.0)
+      actionpack (= 3.2.0)
+      activerecord (= 3.2.0)
+      activeresource (= 3.2.0)
+      activesupport (= 3.2.0)
       bundler (~> 1.0)
-      railties (= 3.0.3)
-    railties (3.0.3)
-      actionpack (= 3.0.3)
-      activesupport (= 3.0.3)
+      railties (= 3.2.0)
+    railties (3.2.0)
+      actionpack (= 3.2.0)
+      activesupport (= 3.2.0)
+      rack-ssl (~> 1.3.2)
       rake (>= 0.8.7)
-      thor (~> 0.14.4)
-    rake (0.8.7)
-    rspec (2.5.0)
-      rspec-core (~> 2.5.0)
-      rspec-expectations (~> 2.5.0)
-      rspec-mocks (~> 2.5.0)
-    rspec-core (2.5.1)
-    rspec-expectations (2.5.0)
+      rdoc (~> 3.4)
+      thor (~> 0.14.6)
+    rake (0.9.2.2)
+    rdoc (3.12)
+      json (~> 1.4)
+    rspec (2.8.0)
+      rspec-core (~> 2.8.0)
+      rspec-expectations (~> 2.8.0)
+      rspec-mocks (~> 2.8.0)
+    rspec-core (2.8.0)
+    rspec-expectations (2.8.0)
       diff-lcs (~> 1.1.2)
-    rspec-mocks (2.5.0)
-    rspec-rails (2.5.0)
-      actionpack (~> 3.0)
-      activesupport (~> 3.0)
-      railties (~> 3.0)
-      rspec (~> 2.5.0)
-    rubyzip (0.9.4)
-    selenium-webdriver (0.1.2)
-      childprocess (~> 0.1.5)
-      ffi (~> 0.6.3)
-      json_pure
-      rubyzip
-    sqlite3 (1.3.3)
+    rspec-mocks (2.8.0)
+    rspec-rails (2.8.1)
+      actionpack (>= 3.0)
+      activesupport (>= 3.0)
+      railties (>= 3.0)
+      rspec (~> 2.8.0)
+    sprockets (2.1.2)
+      hike (~> 1.2)
+      rack (~> 1.0)
+      tilt (~> 1.1, != 1.3.0)
+    sqlite3 (1.3.5)
     thor (0.14.6)
-    treetop (1.4.9)
+    tilt (1.3.3)
+    treetop (1.4.10)
+      polyglot
       polyglot (>= 0.3.1)
-    tzinfo (0.3.24)
-    webrat (0.7.3)
-      nokogiri (>= 1.2.0)
-      rack (>= 1.0)
-      rack-test (>= 0.5.3)
-    xpath (0.1.3)
-      nokogiri (~> 1.3)
+    tzinfo (0.3.31)
 
 PLATFORMS
   ruby
 
 DEPENDENCIES
-  capybara (>= 0.4.0)
+  haml
   jeweler
-  rails (>= 3.0.3)
-  rspec-rails (>= 2.0.0.beta)
+  rails
+  rspec-rails
   sqlite3
-  webrat

data/README.md

@@ -0,0 +1,226 @@
+## Fancygrid
+Fancygrid mades it easy to create and render tables for database records in rails.
+### Features
+* Ajax data fetch
+* Pagination
+* Simple search
+* Complex search with 17 different conditions
+* Column sorting
+* View state caching
+* ActiveRecord supported. MongoDB coming (some day).
+* Column values from attributes, methods, method chains or even custom blocks
+
+### Requirements
+* jQuery >= 1.4.2
+* jQuery-ui (required if column sorting is wanted)
+* Rails 3
+* Haml
+
+### Installation
+In your gemfile
+```ruby
+gem 'fancygrid'
+```
+Run
+```console
+bundle install
+```
+
+If you use Rails3 with asset pipeline enabled, you can just require the javascript and css 
+```
+// = require fancygrid
+```
+If your asset pipeline is disabled, you have to copy the assets from the gems lib directory. There is no generator for this task.
+
+## Getting started
+
+### Basic Setup
+In any controller in any action you can define a fancygrid for a specific model.
+Here is an example for a simple table for the Users model:
+```ruby
+  # UsersController
+  def index
+  
+    fancygrid_for :users do |g|        
+      # specify attributes to display  
+      g.attributes :id, :username, :email 
+      # specify the callback url for ajax loading
+      g.ajax_url = users_path
+      # finally call find to query the data
+      g.find
+    end
+  end
+```
+
+To render the fancygrid in the view, use the same name that you passed in the setup
+```haml
+  # app/views/users/index.html.haml
+  = fancygrid :users
+```
+
+### Static tables
+If you dont want to have an ajax table, dont specify the ajax_url. The data will be
+queried and the table will be rendered without pagination.
+```ruby
+  def index
+    fancygrid_for :users do |g|
+      # ...
+      g.attributes :id, :username, :email 
+      # don't set the ajax_url and just call find
+      g.find
+    end
+  end
+``` 
+
+### Table names and model names
+Usually fancygrid tries to resolve the models class and table name from given 
+name. If you happen to use namespaced models, you must pass the class as an option.
+```ruby
+  def index
+    fancygrid_for :user, :class => Namespace::User do |g|
+      # ...
+    end
+  end
+```
+
+Optionally you can also pass a specific table name. However, if the class responds
+to #table_name, this is not necessary.
+```ruby
+  def index
+    fancygrid_for :user, :class => Namespace::User, :table_name => "users" do |g|
+      # ...
+    end
+  end
+```
+
+## Define columns
+To display attributes as columns use the #attributes method for setup like this:
+```ruby
+  def index  
+    fancygrid_for :users do |g|
+      # ...
+      g.attributes :id, :email, :created_at
+      # ...
+    end
+  end
+```
+
+For everything else use the #columns method. You can have method names,
+method chains and procs to resolve column values.
+```ruby
+  def index  
+    fancygrid_for :users do |g|
+      # ...
+      # methods
+      g.columns :full_name, :some_other_method
+      # method chains
+      g.columns "orders.count"
+      # procs
+      g.columns :roles do |record|
+        record.roles.map(&:name).join(", ")
+      end        
+      # ...
+    end
+  end
+```
+For more complex output you have to format the cell value in the view or a formatter method.
+
+## Columns formatting
+Add a block to the fancygrid call in the view. In there you can use a switch condition
+on the columns name to determine what to render. Do not forget to add the else case to
+render all unformatted values.
+```haml
+  = fancygrid :users do |column, record, value|
+    - case column.name
+    - when :actions
+      = link_to "Show", user_path(record)
+      = link_to "Edit", edit_user_path(record)
+    - else
+      / this else case is important
+      = value
+```
+
+## belongs_to or has_one associations 
+To define columns for associations, use the #columns_for method.
+```ruby
+  def index  
+    fancygrid_for :users do |g|
+      # ...
+      g.columns_for :contact do |contact|
+        contact.attributes :first_name, :last_name
+      end
+      # ...
+      g.find do |query|
+        # eager loading of the association
+        query.select :contact_id
+        query.includes :contact
+      end
+    end
+  end
+```
+Mention that in the query block the contact_id is selected. This is required, since fancygrid
+tries to use optimized sql queries by default. Therefore it will select only those attributes 
+that have been used during the fancygrid setup. If the contact_id is missing, it will not be
+possible to include the contact association.
+
+If your association name is different from the models name, pass the model 
+class as option.
+```ruby
+  def index  
+    fancygrid_for :users do |g|
+      # ...
+      g.columns_for :invoice_address, :class => Address do |adr|
+        adr.attributes :street, :zipcode, :city
+      end
+      # ...
+    end
+  end
+```
+
+## has_many or has_and_belongs_to_many associations
+If you have Users that has_many Orders, you should rather define a fancygrid 
+for the Orders than for Users. However, if it must be a Users table and
+you want to search on the associations attributes, you can do that:
+
+```ruby
+  def index  
+    fancygrid_for :users do |g|
+      # ...
+      g.columns_for :roles do |roles|
+        roles.attributes :name 
+      end
+      # ...
+    end
+  end
+```
+    
+The definition is valid, and you can already search for users with a specific
+role. But nothing is going to be rendered in the roles.name column. This is
+because roles is a collection of records, and not a single record. You can now
+format the column in the view like this
+
+```haml
+  = fancygrid :users do |column, record, value|
+      - case column.identifier
+      - when "roles.name"
+        = record.roles.map(&:name).join("|")
+      - else
+        = value
+```
+
+Here the column identifier is used to identify the column. This is useful
+if you have more columns that are named the same.
+
+## Caching the view state
+To make your users life easier you can enable the view state caching. This way
+the user can search for data, leave the site, come back and have his last
+search back on screen.
+```ruby
+  def index
+    fancygrid_for :users, :persist => true do |grid|
+      # ...
+    end
+  end
+```
+## Copyright
+Copyright (c) 2010 Alexander Graefenstein. See LICENSE for details.