RubyGems - gridify - Versions diffs - 0.1.0 - Mend

gridify 0.1.0

Files changed (26) hide show

data/.rspec +3 -0
data/Gemfile +12 -0
data/Gemfile.lock +26 -0
data/README.rdoc +264 -0
data/Rakefile +47 -0
data/VERSION +1 -0
data/autotest/discover.rb +5 -0
data/init.rb +1 -0
data/lib/gridify.rb +44 -0
data/lib/gridify/assertions.rb +37 -0
data/lib/gridify/grid.rb +149 -0
data/lib/gridify/grid_column.rb +121 -0
data/lib/gridify/grid_finder.rb +197 -0
data/lib/gridify/grid_options.rb +261 -0
data/lib/gridify/grid_view.rb +346 -0
data/spec/db/database.yml +3 -0
data/spec/db/gridify.sqlite3.db +0 -0
data/spec/db/schema.rb +7 -0
data/spec/grid_column_spec.rb +72 -0
data/spec/grid_finder_spec.rb +192 -0
data/spec/grid_spec.rb +38 -0
data/spec/grid_view_spec.rb +423 -0
data/spec/gridify_spec.rb +34 -0
data/spec/spec_helper.rb +20 -0
data/tasks/gridify_tasks.rake +4 -0
metadata +137 -0

data/.rspec ADDED

@@ -0,0 +1,3 @@
+# spec/.rspec
+--color
+--format nested

data/Gemfile ADDED

@@ -0,0 +1,12 @@
+source "http://rubygems.org"
+# Add dependencies required to use your gem here.
+# Example:
+#   gem "activesupport", ">= 2.3.5"
+# Add dependencies to develop your gem here.
+# Include everything needed to run rake, tests, features, etc.
+group :development do
+  gem "bundler", "~> 1.0.0"
+  gem "jeweler", "~> 1.5.2"
+  gem "rspec"
+end

data/Gemfile.lock ADDED

@@ -0,0 +1,26 @@
+GEM
+  remote: http://rubygems.org/
+  specs:
+    diff-lcs (1.1.2)
+    git (1.2.5)
+    jeweler (1.5.2)
+      bundler (~> 1.0.0)
+      git (>= 1.2.5)
+      rake
+    rake (0.8.7)
+    rspec (2.4.0)
+      rspec-core (~> 2.4.0)
+      rspec-expectations (~> 2.4.0)
+      rspec-mocks (~> 2.4.0)
+    rspec-core (2.4.0)
+    rspec-expectations (2.4.0)
+      diff-lcs (~> 1.1.2)
+    rspec-mocks (2.4.0)
+PLATFORMS
+  ruby
+DEPENDENCIES
+  bundler (~> 1.0.0)
+  jeweler (~> 1.5.2)
+  rspec

data/README.rdoc ADDED

@@ -0,0 +1,264 @@
+= Gridify
+A Ruby wrapper and Rails plugin for jqGrid.
+jqGrid is a rich featured data grid built with the jQuery javascript library. http://www.trirand.com/jqgridwiki/doku.php
+Gridify defines a simplified, more consistent API for jqGrid rather than directly emulate the jqGrid api and options in Ruby.
+Gridify tries to respect the MVC (model-view-controller) architecture of your application. This is challenging because grid features span all three areas: it's clearly part of the "view" as it mostly resides in the browser; columns in the table often directly map to columns in the model (database); and grid's ajax requests are handled by controllers. Gridfy gives you some flexibility in managing grids within MVC.
+== Installation
+  $ script/plugin install git://github.com/linoj/gridify.git
+== Scripts
+Be sure to include all the javascripts and stylesheets in the +<head>+ section of your layouts which use the grid, for example
+  <%= stylesheet_link_tag 'application' %>
+  <%= stylesheet_link_tag 'ui/start/jquery-ui-1.7.2.custom' %>
+  <%= stylesheet_link_tag 'ui.jqgrid' %>
+  <%= stylesheet_link_tag 'ui.multiselect' %>
+  <%= javascript_include_tag 'jquery-1.3.2.min' %>
+  <%= javascript_include_tag 'jquery-ui-1.7.2.custom.min' %>
+  <%= javascript_include_tag 'grid.locale-en' %>
+  <%= javascript_include_tag 'jquery.jqGrid' %>
+  <%= javascript_include_tag 'ui.multiselect' %>
+Note: When you download jqGrid, jQuery, and jqUI grab all the bits you'll be using (or just package everything)
+== Examples
+=== Example 1
+Lets say we have an ActiveRecord model "Note" which we want to display in a grid.
+In app/models/note.rb,
+  class Note < ActiveRecord::Base
+    gridify
+  end
+In the NotesController,
+  def index
+    if request.xhr?
+      records = Note.find_for_grid :grid, params
+      render :xml => Note.grid.encode_records(records)
+    else
+      @grid = Note.grid
+    end
+  end
+In the app/views/notes/index.html.erb,
+  <%= @grid %>
+  <h1>Notes Grid<h1>
+  <table id="notes_grid"></table>
+  <div id="notes_grid_pager"></div>
+In this example, +gridify+ creates a default grid named "grid" for the Notes model. In the controller, the #index html action supplies the +@grid+ object used by the view; the #index xml action responds to request +params+ with the encoded data. In the view, +@grid.to_s+ generates the javascript code needed for the grid, which populates the table and pager div.
+=== Example 2
+Here we add some options, including
+* use a grid named "mylist" (allowing multiple grids on a model)
+* limit to specific grid columns
+* ajax requests in json format (instead of xml)
+* enable user resizing the grid width and height
+* enable user arranging and resizing columns
+* enable the search toolbar (search fields atop each column when search button is toggled)
+In app/models/note.rb,
+  class Note < ActiveRecord::Base
+    gridify :mylist,
+      :only => [:title, :body, :updated_at],
+      :data_type => :json,
+      :resizeable => true,
+      :arranger => [:sortable, :hide_show],
+      :search_toolbar => true
+  end
+In the NotesController is same as Example 1 except returns json instead of xml (all the search and sort params are handled by find_for_grid)
+  def index
+    if request.xhr?
+      records = Note.find_for_grid :mylist, params
+      render :json => Note.grid.encode_records(records)
+    else
+      @grid = Note.grid :mylist
+    end
+  end
+In the app/views/notes/index.html.erb is the same as Example 1, except uses "mylist" name
+  <%= @grid %>
+  <h1>My Notes List<h1>
+  <table id="notes_mylist"></table>
+  <div id="notes_mylist_pager"></div>
+=== Example 3
+Here we progressively enhance an html table into a grid. Grid is independent of the ActiveRecord model. No ajax requests.
+In app/views/notes/index.html.erb,
+  <%= Grid.new( Note, :dom_id => "list", :table_to_grid => true ) %>
+  <h1>Notes List</h1>
+  <table id="list">
+    <tr>
+      <th>Title</th>
+      <th>Body</th>
+    </tr>
+    <tbody>
+    <% for note in @notes %>
+      <tr>
+        <td><%=h note.title %></td>
+        <td><%=h note.body %></td>
+      </tr>
+    <% end %>
+    </tbody>
+  </table>
+  <div id="list_pager"></div>
+NotesController#index is standard html response, for example,
+  def index
+    @notes = Note.all
+  end
+=== Example 4
+In the more complex example we take more control of individual columns, including
+* initially hide the created_at column
+* the title column is not resizable
+and allow record (row) editing, adding, and delete via RESTful requests
+In app/models/note.rb,
+  class Note < ActiveRecord::Base
+    gridify :editable => true,
+      :pager => true, :edit_button => true, :add_button => true, :delete_button => true do |grid|
+        grid.column :created_at, :hidden => true
+        grid.column :title, :resizable => false
+      end
+  end
+In the NotesController is same as Example 1, with other actions
+  def index
+    if request.xhr?
+      records = Note.find_for_grid :grid, params
+      render :xml => Note.grid.encode_records(records)
+    else
+      @grid = Note.grid
+    end
+  end
+  def create
+    if request.xhr?
+      note_params = Note.grid.member_params(params)
+      @note = Note.new( note_params )
+      # must return nothing on success (until we setup a format for returning ok vs error)
+      msg = ""
+      unless @note.save
+        @note.errors.entries.each do |error|
+          msg << "<strong>#{error[0]}</strong> : #{error[1]}<br/>"
+        end
+      end
+      render :text => msg
+    else
+      @note = Note.new(params[:note])
+      if @note.save
+        flash[:notice] = "Successfully created note."
+        redirect_to @note
+      else
+        render :action => 'new'
+      end
+    end
+  end
+  def update
+    @note = Note.find(params[:id])
+    if request.xhr?
+      note_params = Note.grid.member_params(params)
+      msg = "success"
+      unless @note.update_attributes( note_params )
+        @note.errors.entries.each do |error|
+          msg << "<strong>#{error[0]}</strong> : #{error[1]}<br/>"
+        end
+      end
+      render :text => msg
+    else
+      if @note.update_attributes(params[:note])
+        flash[:notice] = "Successfully updated note."
+        redirect_to @note
+      else
+        render :action => 'edit'
+      end
+    end
+  end
+  def destroy
+    # NOTE: if allow multiselect should check :id for string of comma delimited id's
+    @note = Note.find(params[:id])
+    @note.destroy
+    if request.xhr?
+      render :nothing => true
+    else
+      flash[:notice] = "Successfully destroyed note."
+      redirect_to notes_url
+    end
+  end
+In the app/views/notes/index.html.erb is the same as Example 1
+  <%= @grid %>
+  <h1>Notes Grid<h1>
+  <table id="notes_grid"></table>
+  <div id="notes_grid_pager"></div>
+For this to work, you should use my fork of jqgrid http://github.com/linoj/jqGrid which adds support for RESTful routes (see http://www.vaporbase.com/postings/jqGrid_for_RESTful_Rails ) until it gets merged.
+The #member_params method maps the attribute parameters into a hash as expected by update_attributes.
+=== Example 5
+By way of better practices, I recommend you ensure the grid javascript is placed in the document header. For example,
+In views/layouts/application.rb, the +<header>+ should include
+  <header>
+    ...
+    <%= yield :head %>
+  </header>
+And in the views, say,
+  <% content_for :head %>
+    <%= @grid %>
+  <% end
+  <h1>Notes Grid<h1>
+  <table id="notes_grid"></table>
+  <div id="notes_grid_pager"></div>
+If it bothers you to put view-specific options in the model, these can be added later (e.g. in the view or in a view helper) using #update. For example,
+  <%= @grid.update( :search_toolbar => false ) %>
+== API
+See the source code for all the options. For most of the grid and view options, see grid_options.rb. For column model options, see grid_column.rb.
+You can escape the Gridify api and use the jqGrid native options directly.
+-----
+Copyright (c) 2010 Jonathan Linowes, released under the MIT license

data/Rakefile ADDED

@@ -0,0 +1,47 @@
+require 'rubygems'
+require 'bundler'
+require 'rake'
+require 'rspec/core/rake_task'
+begin
+  Bundler.setup(:default, :development)
+rescue Bundler::BundlerError => e
+  $stderr.puts e.message
+  $stderr.puts "Run `bundle install` to install missing gems"
+  exit e.status_code
+end
+require 'rake'
+require 'jeweler'
+Jeweler::Tasks.new do |gem|
+  # gem is a Gem::Specification... see http://docs.rubygems.org/read/chapter/20 for more options
+  gem.name = "gridify"
+  gem.homepage = "http://github.com/protectedmethod/gridify"
+  gem.license = "MIT"
+  gem.summary = %Q{Rails wrapper around jqGrid javascript library.}
+  gem.description = %Q{Rails wrapper around jqGrid javascript library.}
+  gem.email = "swalke16@gmail.com"
+  gem.authors = ["swalke16"]
+  # Include your dependencies below. Runtime dependencies are required when using your gem,
+  # and development dependencies are only needed for development (ie running rake tasks, tests, etc)
+  #  gem.add_runtime_dependency 'jabber4r', '> 0.1'
+  #  gem.add_development_dependency 'rspec', '> 1.2.3'
+end
+Jeweler::RubygemsDotOrgTasks.new
+desc 'Run the specs'
+RSpec::Core::RakeTask.new do |t|
+  t.pattern = "./spec/**/*_spec.rb" # don't need this, it's default.
+end
+task :default => :spec
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "gridify #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION ADDED

	@@ -0,0 +1 @@
1	+ 0.1.0

data/autotest/discover.rb ADDED

@@ -0,0 +1,5 @@
+$:.push(File.join(File.dirname(__FILE__), %w[.. .. rspec]))
+Autotest.add_discovery do
+  "rspec"
+end

data/init.rb ADDED

	@@ -0,0 +1 @@
1	+ require 'gridify'

data/lib/gridify.rb ADDED

@@ -0,0 +1,44 @@
+require 'gridify/grid'
+module Gridify
+  def self.included(base)
+    base.extend(ClassMethods)
+  end
+  module ClassMethods
+    attr_accessor :grids
+    def gridify(*args, &block)
+      # debugger
+      grid = Gridify::Grid.new( self, *args, &block)
+      @grids ||= {}
+      @grids[grid.name.to_sym] = grid
+      unless self.respond_to?(:find_for_grid)
+        class_eval <<-EOV
+            named_scope :find_for_grid, lambda {|name, params|
+              grid = grids[name]
+              grid.update_from_params( params )
+              grid.current_scope
+            }
+        EOV
+      end
+    end
+    def grids
+      @grids || {}
+    end
+    def grid
+      grids[:grid]
+    end
+  end
+end
+class ActiveRecord::Base
+  include Gridify
+end

data/lib/gridify/assertions.rb ADDED

@@ -0,0 +1,37 @@
+# lifted from state_machine plugin
+module Gridify
+  # Provides a set of helper methods for making assertions about the content
+  # of various objects
+  module Assertions
+    # Validates that the given hash *only* includes the specified valid keys.
+    # If any invalid keys are found, an ArgumentError will be raised.
+    #
+    # == Examples
+    #
+    #   options = {:name => 'John Smith', :age => 30}
+    #
+    #   assert_valid_keys(options, :name)           # => ArgumentError: Invalid key(s): age
+    #   assert_valid_keys(options, 'name', 'age')   # => ArgumentError: Invalid key(s): age, name
+    #   assert_valid_keys(options, :name, :age)     # => nil
+    def assert_valid_keys(hash, *valid_keys)
+      invalid_keys = hash.keys - valid_keys
+      raise ArgumentError, "Invalid key(s): #{invalid_keys.join(', ')}" unless invalid_keys.empty?
+    end
+    # Validates that the given hash only includes at *most* one of a set of
+    # exclusive keys.  If more than one key is found, an ArgumentError will be
+    # raised.
+    #
+    # == Examples
+    #
+    #   options = {:only => :on, :except => :off}
+    #   assert_exclusive_keys(options, :only)                   # => nil
+    #   assert_exclusive_keys(options, :except)                 # => nil
+    #   assert_exclusive_keys(options, :only, :except)          # => ArgumentError: Conflicting keys: only, except
+    #   assert_exclusive_keys(options, :only, :except, :with)   # => ArgumentError: Conflicting keys: only, except
+    def assert_exclusive_keys(hash, *exclusive_keys)
+      conflicting_keys = exclusive_keys & hash.keys
+      raise ArgumentError, "Conflicting keys: #{conflicting_keys.join(', ')}" unless conflicting_keys.length <= 1
+    end
+  end
+end