jqgrid_for_rails 1.0.0 → 1.0.1

data/CHANGELOG.rdoc

@@ -1,3 +1,14 @@
+== 1.0.1
+
+* enhancements
+  * Add helper to easily create the col_model. (col_model_for_jqgrid)
+  * Support prefix in the id column of the json response.
+  * Support I18n localization of date fields in the json response.
+
+* bug fixes
+  * In 'json_for_jqgrid' method do not return nil if +records+ is empty and return the
+    json string in spite of that.
+
 == 1.0.0
 
 * enhancements

data/README.rdoc

@@ -2,7 +2,7 @@
 
 This is a simple plug-in to create a JqGrid[http://www.trirand.com/blog] javascript code easily inside rails views.
 
-It is extremely flexible, all the ruby code is converted to java script code, so you can use all the jqgrid supported features. It is not an abstraction layer from the jqGrid apis, instead, you type the same code you would do to crate the grid using javascript but in Ruby. The code should follow the jqgrid api definition.
+It is extremely flexible, all the ruby code is converted to java script code, so you can use all the jqgrid supported features. It is not an abstraction layer from the jqGrid apis, instead, you type the same code you would do to create the grid using javascript but in Ruby. The code should follow the jqgrid api definition.
 
 For example, to get this java script code:
 
@@ -115,6 +115,44 @@ Don't forget to include the jquery and jqgrid javascript and stylesheet files!
 
 There are convenient methods available in the controllers
 
+=== col_model_for_jqgrid
+
+This method easily creates an array to be used as col_model.
+
+  col_model_for_jqgrid(['inv_date', 'total' ], {:width => 100})
+
+    #=> [{:name=>"inv_date", :index=>"inv_date", :width=>100}, {:name=>"total", :index=>"total", :width=>100}]
+
+
+So, in the controller:
+
+  # app/controllers/invoices_controller.rb
+
+  class InvoicesController < ApplicationController
+
+    def show
+      @col_model = col_model_for_jqgrid(['inv_date', 'total' ], {:width => 180})
+    end
+  end
+
+
+And then you can use it when creating the grid in the helper:
+
+  grid = [{
+    :url => '/invoices',
+    :datatype => 'json',
+    :mtype => 'GET',
+    :colNames => ['Inv No','Date'],
+    :colModel  => @col_model,
+    :pager => '#invoices_pager',
+    :rowNum => 10,
+    :rowList => [10, 20, 30],
+    :caption => 'My first grid',
+    :onSelectRow => "function() { alert('Row selected!');}".to_json_var
+  }]
+
+  jqgrid_api 'invoices_list', grid
+
 === json_for_jqgrid
 
 This method generates the json response for the grid. It takes the records found by the +paginate+ method offered by will_paginate[https://github.com/mislav/will_paginate].

data/lib/app/helpers/jqgrids_helper.rb

@@ -6,8 +6,8 @@ module JqgridsHelper
   #
   # ==== Parameters
   #
-  # * +grid_id+ - This is the id of the html table tag that will contain the grid.
-  # * +*args+ - Each item in the args array will be translated to a jqgrid api function. Each item
+  # * <tt>grid_id</tt> - This is the id of the html table tag that will contain the grid.
+  # * <tt>*args</tt> - Each item in the args array will be translated to a jqgrid api function. Each item
   #   should be an array whose elements will be encoded to json to create the jqgrid api function.
   #   All subsequent functions after the first one will be chained.
   #   See the examples for details.
@@ -16,21 +16,19 @@ module JqgridsHelper
   #
   # This method accepts an options hash as their last parameter. The accepted options are:
   #
-  # [:script_tags]
-  #   If false, <script> tags will not be generated. Default true.
+  # * <tt>:script_tags</tt> - If <tt>false</tt>, <tt><script></tt> tags will not be generated. Default +true+.
   #
-  # [:on_document_ready]
-  #   If true, all the javascript code will be enclosed inside a +jQuery(document).ready+ function.
+  # * <tt>:on_document_ready</tt> - If <tt>true</tt>, all the javascript code will be enclosed inside a <tt>jQuery(document).ready</tt> function.
   #
   # ==== Examples
   #
   # A simple call to generate a navigation bar:
   #
   #   jqgrid_api 'invoices_list', [:navGrid, '#invoices_pager', {:search => true, :refresh => false}]
-  #     => jQuery("#invoices_list").jqGrid("navGrid", "#invoices_pager", {"search":true,"refresh":false});
+  #     #=> jQuery("#invoices_list").jqGrid("navGrid", "#invoices_pager", {"search":true,"refresh":false});
   #
   # A more complete example, to create a grid and a pager with a custom button, without the script tags
-  # and with the js code enclosed inside a a +jQuery(document).ready+ function.
+  # and with the js code enclosed inside a <tt>jQuery(document).ready</tt> function.
   #
   #   options = {:on_document_ready => true, :html_tags => false}
   #
@@ -85,14 +83,14 @@ module JqgridsHelper
   #
   # jQgrid accepts three different formats to set the pager id option.
   #
-  # 1 - jQuery('#my_pager_div')
-  # 2 - #my_pager_div
-  # 3 - my_pager_div
+  # 1. <tt>jQuery('#my_pager_div')</tt>
+  # 2. <tt>#my_pager_div</tt>
+  # 3. <tt>my_pager_div</tt>
   #
   # ==== Example
   #
   #   pager_id_from_options({:pager => "jQuery('#my_pager_id')"})
-  #     => 'my_pager_id'
+  #     #=> 'my_pager_id'
   #
   def pager_id_from_options options
     pager_option = options[:pager]

data/lib/jqgrid_for_rails/controllers/helpers.rb

@@ -2,55 +2,131 @@ module JqgridForRails
   module Controllers
     # Those helpers are convenience methods added to ApplicationController.
     module Helpers
-      
-      # Returns a json string ready to be send to a jqgrid component.
+
+      # Returns an array to be used as col_model for the grid where each item
+      # is a hash for each column. Each hash will have at least two keys by
+      # default, the +name+ and the +index+, whose values will be the name of
+      # the column. Other keys will be included if present in the +options+
+      # hash.
       #
-      # +records+ should be the result of an active record query through
-      # the +paginate+ method offered by will_paginate.
+      # * +columns+ - Array with the name of the columns to include in the
+      #   col_model.
       #
-      # +columns+ is an array with the name of the fields in the order they
-      # should be returned.
+      # ==== Options
       #
-      # === Options
+      # Every item in the options hash will be a property in the col_model for
+      # every column, unless the item is also a hash, where only will be included
+      # in the specified columns. An item can be also a Proc, that will be called
+      # passing +columns+ as parameter.
       #
-      # [:id_column]
-      #   Says which is the column that should be used as the row id
+      # ==== Examples
       #
-      # [:page]
-      #   Says the page number (Deprecated. The page number is now inferred from +records+)
+      #   col_model_for_jqgrid(['inv_date', 'total' ])
       #
-      def json_for_jqgrid records, columns = nil, options = {}
+      #     #=> [{:name=>"inv_date", :index=>"inv_date"}, {:name=>"total", :index=>"total"}]
+      #
+      #   col_model_for_jqgrid(['inv_date', 'total' ], {:width => 100})
+      #
+      #     #=> [{:name=>"inv_date", :index=>"inv_date", :width=>100}, {:name=>"total", :index=>"total", :width=>100}]
+      #
+      #   col_model_for_jqgrid(['inv_date', 'total'], {:width => {'inv_date' => 100}})
+      #
+      #     #=> [{:name => 'inv_date', :index => 'inv_date', :width => 100}, {:name => 'total', :index => 'total'}]
+      #
+      #   col_model_for_jqgrid(['inv_date'], {:prop => Proc.new {|c| c.camelize}})
+      #
+      #     #=> [{:name => 'inv_date', :index => 'inv_date', :prop => 'InvDate'}]
+      #
+      def col_model_for_jqgrid columns, options = {}
+        columns.map do |c|
+          h = {:name => c, :index => c}
+          h.merge property_from_options(c, options)
+        end
 
-        return if records.empty?
+      end
 
-        columns ||= records.first.attributes.keys
+      # Returns a json string ready to be sent to a jqgrid component.
+      #
+      # * +records+ - Should be the result of an active record query through
+      #   the +paginate+ method offered by will_paginate.
+      # * +columns+ - Array with the name of the fields in the order they
+      #   should be returned.
+      #
+      # ==== Options
+      #
+      # * <tt>:id_column</tt> - Says which is the column that should be used as
+      #   the row id.
+      #
+      # * <tt>:id_prefix</tt> - If specified, the +column_id+ option will be
+      #   concatenated to this prefix. This helps to keep the html id unique in
+      #   the document.
+      #
+      # * <tt>:translate</tt> - Array with the name of the fields that should be
+      #   localized with the <tt>I18n.l</tt> method. The field content must be
+      #   of any class accepted by the method. I.e. Time, DateTime, Date.
+      #
+      # * <tt>:page</tt> - Says the page number (Deprecated. The page number is
+      #   now inferred from +records+.
+      #
+      def json_for_jqgrid records, columns = nil, options = {}
+
+        columns ||= (records.first.attributes.keys rescue [])
 
         options[:id_column] ||= columns.first
         options[:page]      ||= records.current_page
 
-        { :page => options[:page],
-          :total => records.total_pages,
-          :records => records.total_entries,
-          :rows => records.map do |r| {
-            :id => r.attributes[options[:id_column]],
-            :cell => r.attributes.values_at(*columns)}
-          end
+        { :page     => options[:page],
+          :total    => records.total_pages,
+          :records  => records.total_entries,
+          :rows     => records.map {|r| row_from_record(r, columns, options)}
         }.to_json
       end
 
       # Returns the 'order by' string created using the params received from the jqgrid.
       #
-      # === Example
+      # ==== Example
       #
       #   order_by_from_params({'sidx' => 'updated_at', 'sord' => 'asc'})
-      #   => 'updated_at asc'
+      #   #=> 'updated_at asc'
       #
       def order_by_from_params params
         order_by = params['sidx'] unless params['sidx'].blank?
         order_by << " #{params['sord']}" if params['sord'] && order_by
         order_by
       end
-    
+
+    private
+
+      # Returns a hash with the values for a jqgrid json row.
+      def row_from_record(r, columns, options)
+        attribs = r.attributes
+
+        # Localize Date, Time or DateTime fields
+        locale_classes = [Time, Date, DateTime]
+        if options[:translate].is_a?(Array) && I18n
+          options[:translate].each do |col|
+            attribs[col.to_s] = I18n.l(attribs[col.to_s]) if locale_classes.include?(attribs[col.to_s].class)
+          end
+        end
+
+        {:id => "#{options[:id_prefix]}#{attribs[options[:id_column]]}",
+         :cell => attribs.values_at(*columns) }
+      end
+
+      def property_from_options col_name, options
+        h = {}
+        options.each do |k, v|
+          case v.class.to_s
+          when "Proc"
+            h[k] = v.call(col_name)
+          when "Hash"
+            h[k] = v[col_name] if v.has_key?(col_name)
+          else
+            h[k] = v
+          end
+        end
+        h
+      end
     end
   end
 end

data/lib/jqgrid_for_rails/version.rb

@@ -1,4 +1,4 @@
 module JqgridForRails
-  VERSION = "1.0.0".freeze
+  VERSION = "1.0.1".freeze
 end
 

data/test/controllers/helpers_test.rb

@@ -31,4 +31,77 @@ class ControllerHelpersTest < ActionController::TestCase
     assert_nil @controller.order_by_from_params(params)
   end
 
+  test "json_for_grid with empty records result" do
+    records = Invoice.paginate(:page => 1)
+    json    = @controller.json_for_jqgrid(records)
+    hash    = ActiveSupport::JSON.decode(json)
+    assert_equal 0, hash['total']
+    assert_equal [], hash['rows']
+    assert_equal 1, hash['page']
+    assert_equal 0, hash['records']
+  end
+
+  test "json_for_grid with one record and id prefix" do
+    tmp_record  = Invoice.create({:invid => 1, :invdate => '2011-01-01 00:00:00', :amount => 10, :tax => 1, :total => 11, :note => '' })
+    records     = Invoice.paginate(:page => 1)
+    json        = @controller.json_for_jqgrid(records, ['invdate', 'amount', 'total' ], {:id_column => 'invid', :id_prefix => 'mygrid_row_'})
+    hash        = ActiveSupport::JSON.decode(json)
+    Invoice.delete(tmp_record.id)
+    assert_equal hash["total"], 1
+    assert_equal hash["page"], 1
+    assert_equal hash["records"], 1
+    assert_equal hash["rows"][0]["cell"], [Time.utc('2011-01-01 00:00:00'), 10.0, 11.0]
+    assert_equal hash["rows"][0]["id"], "mygrid_row_1"
+  end
+
+  test "col_model_for_jqgrid should return a valid model for the grid" do
+    columns = ['inv_date', 'amount', 'total' ]
+    result  = @controller.col_model_for_jqgrid(columns)
+    assert_equal [
+      {:name => 'inv_date', :index => 'inv_date'},
+      {:name => 'amount', :index => 'amount'},
+      {:name => 'total', :index => 'total'}
+      ], result
+  end
+
+  test "col_model_for_jqgrid with default width for every column" do
+    columns = ['inv_date', 'amount', 'total' ]
+    result  = @controller.col_model_for_jqgrid(columns, {:width => 100})
+    assert_equal [
+      {:name => 'inv_date', :index => 'inv_date', :width => 100},
+      {:name => 'amount', :index => 'amount', :width => 100},
+      {:name => 'total', :index => 'total', :width => 100}
+      ], result
+  end
+
+  test "col_model_for_jqgrid with explicity width for some columns" do
+    columns = ['inv_date', 'amount', 'total' ]
+    result  = @controller.col_model_for_jqgrid(columns, {:width => {'inv_date' => 100, 'total' => 150}})
+    assert_equal [
+      {:name => 'inv_date', :index => 'inv_date', :width => 100},
+      {:name => 'amount', :index => 'amount'},
+      {:name => 'total', :index => 'total', :width => 150}
+      ], result
+  end
+
+  test "col_model_for_jqgrid with explicity property for some columns" do
+    columns = ['inv_date', 'amount', 'total' ]
+    result  = @controller.col_model_for_jqgrid(columns, {:property_1 => {'inv_date' => 'high', 'total' => 'low'}, :property_2 => true})
+    assert_equal [
+      {:name => 'inv_date', :index => 'inv_date', :property_1 => 'high', :property_2 => true},
+      {:name => 'amount', :index => 'amount', :property_2 => true},
+      {:name => 'total', :index => 'total', :property_1 => 'low', :property_2 => true}
+      ], result
+  end
+
+  test "col_model_for_jqgrid with proc as property" do
+    columns = ['inv_date', 'amount', 'total' ]
+    result  = @controller.col_model_for_jqgrid(columns, {:property_1 => Proc.new {|c| c.camelize}})
+    assert_equal [
+      {:name => 'inv_date', :property_1 => 'InvDate', :index => 'inv_date'},
+      {:name => 'amount', :property_1 => 'Amount', :index => 'amount'},
+      {:name => 'total', :property_1 => 'Total', :index => 'total'}
+      ], result
+  end
+
 end

data/test/jqgrids_helper_test.rb

@@ -81,13 +81,12 @@ class JqgridsHelperTest < Test::Unit::TestCase
   def test_chained_functions
     @template = MockView.new
     div_id = 'my_grid'
-    functions = [
-      [:navButtonAdd, '#pager', { :caption => 'Add'}],
-      [:navSeparatorAdd, '#pager']]
+    nav_button =  [:navButtonAdd, '#pager', { :caption => 'Add'}]
+    nav_separator =  [:navSeparatorAdd, '#pager']
 
     expected = 'jQuery("#'+div_id+'").jqGrid("navButtonAdd", "#pager", {"caption":"Add"}).jqGrid("navSeparatorAdd", "#pager");'
 
-    assert_equal expected, @template.jqgrid_api(div_id, *functions, {:script_tags => false})
+    assert_equal expected, @template.jqgrid_api(div_id, nav_button, nav_separator, {:script_tags => false})
 
   end
 

metadata

@@ -5,8 +5,8 @@ version: !ruby/object:Gem::Version
   segments: 
   - 1
   - 0
-  - 0
-  version: 1.0.0
+  - 1
+  version: 1.0.1
 platform: ruby
 authors: 
 - Juan Manuel Cuello
@@ -14,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-30 00:00:00 -03:00
+date: 2011-04-13 00:00:00 -03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency