jqgrid_for_rails 0.2.0 → 1.0.0

data/CHANGELOG.rdoc

@@ -1,8 +1,18 @@
+== 1.0.0
+
+* enhancements
+  * Support for chained functions.
+  * The 'jqgrid' method is renamed and rewritten to fully support calls to jqgrid apis.
+  * Get the page number for the json response from the will_paginate resultset.
+
+* bug fixes
+  * Fix order_by_from_params when sidx is blank.
+
 == 0.2.0
 
 * enhancements
   * Navigator options fully supported.
 
-* bug fix
+* bug fixes
   * Get pager id from the options hash in any of the formats accepted by
     jqGrid.

data/README.rdoc

@@ -1,13 +1,18 @@
 == JqgridForRails
 
-This is a simple plug-in to create JqGrid(http://www.trirand.com/blog) javascript code easily and cleaner inside rails views.
+This is a simple plug-in to create a JqGrid[http://www.trirand.com/blog] javascript code easily inside rails views.
 
-== Example
+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.
 
-There is an example application at:
+For example, to get this java script code:
 
-https://github.com/Juanmcuello/jqgrid_for_rails_example
+  jQuery("#invoices_list").jqGrid("navGrid", "#invoices_pager", {"search":true,"refresh":false});
+
+You should type in ruby:
 
+  jqgrid_api 'invoices_list', [:navGrid, '#invoices_pager', {:search => true, :refresh => false}]
+
+See below for more examples.
 
 == Installation
 
@@ -20,9 +25,18 @@ As a plugin:
   $ rails plugin install git://github.com/Juanmcuello/jqgrid_for_rails.git
 
 
+== Examples
+
+There is an example application at:
+
+https://github.com/Juanmcuello/jqgrid_for_rails_example
+
+
 == Views
 
-To generate the grid, you can first create a method in a helper and then call the +jqgrid+ method to generate the java script code. For example, if you have an invoices_helper.rb file, you can define a method there:
+To generate the grid, you can first create a method in a helper and then call the +jqgrid_api+ method to generate the java script code. For example, if you have an _invoices_helper.rb_ file, you can define a method there:
+
+  # app/helpers/invoices_helper.rb
 
   module InvoicesHelper
 
@@ -30,66 +44,68 @@ To generate the grid, you can first create a method in a helper and then call th
 
     def invoices_jqgrid
 
-      options = {:html_tags => true}
-      grid_options = {
+      grid = [{
         :url => '/invoices',
         :datatype => 'json',
         :mtype => 'GET',
         :colNames => ['Inv No','Date'],
         :colModel  => [
-          { :name => 'invid',   :index => 'invid',    :width => 55 },
-          { :name => 'invdate', :index => 'invdate',  :width => 90 },
+          { :name => 'invid',   :index => 'invid',    :width => 180 },
+          { :name => 'invdate', :index => 'invdate',  :width => 180 },
         ],
         :pager => '#invoices_pager',
         :rowNum => 10,
         :rowList => [10, 20, 30],
         :caption => 'My first grid',
         :onSelectRow => "function() { alert('Row selected!');}".to_json_var
-      }
+      }]
 
-      jqgrid 'invoices_list', options, grid_options
+      jqgrid_api 'invoices_list', grid
     end
   end
 
 Now you can use the helper in the view:
 
+  # app/views/invoices/index.html.erb
+
+  <table id=invoices_list></table>
+  <div id=invoices_pager></div>
+
   <%= raw(invoices_jqgrid) %>
 
+
 Or, if you are using Rails 2.3.x :
 
   <%= invoices_jqgrid %>
 
 This will result in something like:
 
-  <table id="invoices_list"></table>
-  <div id="invoices_pager"></div>
+  <table id=invoices_list></table>
+  <div id=invoices_pager></div>
+
   <script>
     jQuery("#invoices_list").jqGrid({
-      "url": "/invoices",
-      "datatype": "json",
-      "mtype": "GET",
-      "colNames": ["Inv No","Date"],
-      "colModel": [
-        {"name":"invid", "index":"invid", "width":55},
-        {"name":"invdate", "index":"invdate", "width":90}],
-      "pager": "#invoices_pager",
-      "rowNum": 10,
-      "rowList": [10,20,30],
-      "caption": "My first grid",
-      "onSelectRow": function() { alert('Row selected!');}});
-
-    jQuery("#invoices_list").jqGrid("navGrid", "#invoices_pager", {});
-
-  </script
+      "url":"/invoices",
+      "datatype":"json",
+      "mtype":"GET",
+      "colNames":["Inv No","Date"],
+      "colModel":[
+        {"name":"invid","index":"invid","width":180},
+        {"name":"invdate","index":"invdate","width":180}],
+      "pager":"#invoices_pager",
+      "rowNum":10,
+      "rowList":[10,20,30],
+      "caption":"My first grid",
+      "onSelectRow":function() { alert('Row selected!');}
+    });
+  </script>
 
 Note: resulting code was indented for clarification.
 
-You can do it better using +content_for+ :
-
-At the views:
+You can do it better using +content_for+ in the view:
 
   <% content_for :head do %>
-    <%= invoices_jqgrid %>
+    <%= raw(invoices_jqgrid) %>
   <% end %>
 
 
@@ -97,19 +113,36 @@ Don't forget to include the jquery and jqgrid javascript and stylesheet files!
 
 == Controllers
 
-You can use the +json_for_jqgrid+ method at the controllers to generate the json response for the grid. It receives the records found by the +paginate+ method offered by will_paginate[https://github.com/mislav/will_paginate].
+There are convenient methods available in the controllers
 
-  def index
+=== json_for_jqgrid
 
-    @columns = ['invid', 'invdate']
+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].
 
-    @invoices = Invoice.paginate(:page => params[:page], :per_page => params[:rows] )
+In the controller:
 
-    if request.xhr?
-      render :json => json_for_jqgrid(@invoices, @columns, {:page => params[:page]})
+  # app/controllers/invoices_controller.rb
+
+  class InvoicesController < ApplicationController
+
+    def index
+      @columns = ['invid', 'invdate']
+      @invoices = Invoice.paginate(:page => params[:page], :per_page => params[:rows])
+
+      if request.xhr?
+        render :json => json_for_jqgrid(@invoices, @columns)
+      end
     end
   end
 
+=== order_by_from_params
+
+This method creates an active record +order+ string using the params sent by the grid.
+
+  @invoices = Invoice.paginate(
+    :page     => params[:page],
+    :per_page => params[:rows],
+    :order    => order_by_from_params(params))
 
 == Maintainers
 

data/lib/app/helpers/jqgrids_helper.rb

@@ -1,94 +1,86 @@
 module JqgridsHelper
 
-  # Generates the jqGrid javascript code. Also html tags for the table and pager can be generated.
-  # The javascript code is enclosed between the <script> tags.
+  # Generates the jqGrid javascript code. This method returns a jqgrid api function after parsing the
+  # received parameters. If more than one function is specified in the parameters, all the resulting
+  # functions will be chained.
   #
-  # The +grid_id+ parameter should be the id of the html table tag that will contain the grid.
-  # If [:html_tags] is +true+, the grid_id will be used when creating the <table> tags.
+  # ==== Parameters
   #
-  # === Options
+  # * +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
+  #   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.
   #
-  # [:html_tags]
-  #   If true, <table> tag for the grid, and <div> tag for the table will be generated as well.
+  # ==== Options
   #
-  # [:on_document_ready]
-  #   If true, all the javascript code will be enclosed inside a +jQuery(document).ready+ function
+  # This method accepts an options hash as their last parameter. The accepted options are:
   #
-  # === Grid Options
+  # [:script_tags]
+  #   If false, <script> tags will not be generated. Default true.
   #
-  # This hash can contain any option accepted by the jqGrid. The has will encoded to json to create
-  # the javascript code for the grid.
+  # [:on_document_ready]
+  #   If true, all the javascript code will be enclosed inside a +jQuery(document).ready+ function.
   #
-  # See http://www.trirand.com/jqgridwiki/doku.php?id=wiki:options
+  # ==== Examples
   #
-  # For options that represents javascript functions, the value should be converted to a json_var
-  # using the +to_json_var+ method.
+  # A simple call to generate a navigation bar:
   #
-  # For example:
-  # :onLoadComplete => "function() { alert('This is a function!');}".to_json_var
+  #   jqgrid_api 'invoices_list', [:navGrid, '#invoices_pager', {:search => true, :refresh => false}]
+  #     => jQuery("#invoices_list").jqGrid("navGrid", "#invoices_pager", {"search":true,"refresh":false});
   #
-  # === Nav Options
+  # 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.
   #
-  # This hash can contain any option accepted by the nav options of jqGrid.
+  #   options = {:on_document_ready => true, :html_tags => false}
   #
-  # === Example
+  #   grid = [{
+  #     :url => '/invoices',
+  #     :datatype => 'json',
+  #     :mtype => 'GET',
+  #     :colNames => ['Inv No','Date', 'Amount','Tax','Total','Notes'],
+  #     :colModel  => [
+  #       { :name => 'invid',   :index => 'invid',    :width => 55 },
+  #       { :name => 'invdate', :index => 'invdate',  :width => 90 },
+  #       { :name => 'amount',  :index => 'amount',   :width => 80,   :align => 'right' },
+  #       { :name => 'tax',     :index => 'tax',      :width => 80,   :align => 'right' },
+  #       { :name => 'total',   :index => 'total',    :width => 80,   :align => 'right' },
+  #       { :name => 'note',    :index => 'note',     :width => 150,  :sortable => false }
+  #     ],
+  #     :pager => '#invoices_pager',
+  #     :rowNum => 10,
+  #     :rowList => [10, 20, 30],
+  #     :sortname => 'invid',
+  #     :sortorder => 'desc',
+  #     :viewrecords => true,
+  #     :caption => 'My first grid',
+  #     :onSelectRow => "function() { alert('Row selected!');}".to_json_var
+  #   }]
   #
-  #  options = {:on_document_ready => true, :html_tags => false}
+  #   pager = [:navGrid, "#invoices_pager", {:del => true }, {}, {}, {:closeOnEscape => true}]
   #
-  #  grid_options = {
-  #    :url => '/invoices',
-  #    :datatype => 'json',
-  #    :mtype => 'GET',
-  #    :colNames => ['Inv No','Date', 'Amount','Tax','Total','Notes'],
-  #    :colModel  => [
-  #      { :name => 'invid',   :index => 'invid',    :width => 55 },
-  #      { :name => 'invdate', :index => 'invdate',  :width => 90 },
-  #      { :name => 'amount',  :index => 'amount',   :width => 80,   :align => 'right' },
-  #      { :name => 'tax',     :index => 'tax',      :width => 80,   :align => 'right' },
-  #      { :name => 'total',   :index => 'total',    :width => 80,   :align => 'right' },
-  #      { :name => 'note',    :index => 'note',     :width => 150,  :sortable => false }
-  #    ],
-  #    :pager => '#invoices_pager',
-  #    :rowNum => 10,
-  #    :rowList => [10, 20, 30],
-  #    :sortname => 'invid',
-  #    :sortorder => 'desc',
-  #    :viewrecords => true,
-  #    :caption => 'My first grid',
-  #    :onSelectRow => "function() { alert('Row selected!');}".to_json_var
-  #  }
+  #   pager_button = [:navButtonAdd, "#invoices_pager", {:caption => 'Add', :onClickButton => 'function() {alert("Button!")}'.to_json_var }]
   #
-  #  jqgrid 'invoices_list', options, grid_options
+  #   jqgrid_api 'invoices_list', grid, pager, pager_button, options
   #
-  def jqgrid grid_id, options = {}, grid_options = {}, *nav_options
-
-    html_output = []
-
-    # Table
-    html_output << content_tag(:table, nil, :id => grid_id) if options[:html_tags]
-    js_output   =  "jQuery(\"##{grid_id}\").jqGrid(#{grid_options.to_json});"
-
-    # Pager
-    if grid_options[:pager]
+  #
+  def jqgrid_api div_id, *args
 
-      pager_id = pager_id_from_options(grid_options)
+    options = args.extract_options!
 
-      html_output << content_tag(:div, nil, :id => pager_id) if options[:html_tags]
+    options[:on_document_ready] ||= false
+    options[:script_tags] = true if options[:script_tags].nil?
 
-      unless nav_options.empty?
-        js_output << "jQuery(\"##{grid_id}\").jqGrid(\"navGrid\", \"##{pager_id}\", #{format_nav_options(nav_options)});"
-      end
+    result = args.map do |v|
+      ".jqGrid(#{v.map { |v| (v || {}).to_json}.join(', ')})"
     end
+    js = "jQuery(\"##{div_id}\")" + result.join('') + ';'
 
-    wrap_with_document_ready! js_output if options[:on_document_ready]
-
-    html_output << "<script>" << js_output << "</script>"
-
-    html_output.join("\n")
+    wrap_with_document_ready!(js)  if options[:on_document_ready]
+    wrap_with_script_tags!(js)     if options[:script_tags]
+    js
   end
 
-private
-
   # Extracts the pager id from the options hash.
   #
   # jQgrid accepts three different formats to set the pager id option.
@@ -97,7 +89,7 @@ private
   # 2 - #my_pager_div
   # 3 - my_pager_div
   #
-  # === Example
+  # ==== Example
   #
   #   pager_id_from_options({:pager => "jQuery('#my_pager_id')"})
   #     => 'my_pager_id'
@@ -117,12 +109,14 @@ private
     end
   end
 
+private
+
   def wrap_with_document_ready! str
     str.replace("jQuery(document).ready(function() {#{str}});")
   end
 
-  def format_nav_options nav_options
-    nav_options.map {|e| (e || {}).to_json}.join(', ')
+  def wrap_with_script_tags! str
+    str.replace("<script>\n#{str}\n</script>")
   end
 
 end

data/lib/jqgrid_for_rails/controllers/helpers.rb

@@ -16,8 +16,8 @@ module JqgridForRails
       # [:id_column]
       #   Says which is the column that should be used as the row id
       #
-      # :page]
-      #   Says the page number
+      # [:page]
+      #   Says the page number (Deprecated. The page number is now inferred from +records+)
       #
       def json_for_jqgrid records, columns = nil, options = {}
 
@@ -26,7 +26,7 @@ module JqgridForRails
         columns ||= records.first.attributes.keys
 
         options[:id_column] ||= columns.first
-        options[:page]      ||= 1
+        options[:page]      ||= records.current_page
 
         { :page => options[:page],
           :total => records.total_pages,
@@ -46,7 +46,7 @@ module JqgridForRails
       #   => 'updated_at asc'
       #
       def order_by_from_params params
-        order_by = params['sidx'] if params['sidx']
+        order_by = params['sidx'] unless params['sidx'].blank?
         order_by << " #{params['sord']}" if params['sord'] && order_by
         order_by
       end

data/lib/jqgrid_for_rails/version.rb

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

data/test/controllers/helpers_test.rb

@@ -26,4 +26,9 @@ class ControllerHelpersTest < ActionController::TestCase
     assert_nil @controller.order_by_from_params(params)
   end
 
+  test "order_by_from with blank sidx" do
+    params = {'sidx' => ''}
+    assert_nil @controller.order_by_from_params(params)
+  end
+
 end

data/test/jqgrids_helper_test.rb

@@ -11,15 +11,13 @@ class JqgridsHelperTest < Test::Unit::TestCase
     @template = MockView.new
 
     grid_id = 'grid_id'
-    options = {:html_tags => true}
-    grid_options = { :url => "/jqGridModel?model=Wine" }
+    grid_options = [{:url => "/jqGridModel?model=Wine" }]
 
-    expected  = '<table id="'+grid_id+'"></table>' + "\n"
-    expected << '<script>' + "\n"
+    expected =  '<script>' + "\n"
     expected <<    'jQuery("#'+grid_id+'").jqGrid({"url":"/jqGridModel?model=Wine"});' + "\n"
     expected << '</script>'
 
-    assert_equal(expected, @template.jqgrid(grid_id, options , grid_options))
+    assert_equal(expected, @template.jqgrid_api(grid_id, grid_options, {:script_tags => true}))
 
   end
 
@@ -27,57 +25,51 @@ class JqgridsHelperTest < Test::Unit::TestCase
 
     @template = MockView.new
 
-    grid_id = 'grid_id'
-    pager_id = 'gridpager'
-    grid_options = { :pager => "jQuery('##{pager_id}')".to_json_var }
+    grid_id       = 'grid_id'
+    pager_id      = 'gridpager'
+    grid_options  = [{:pager => "jQuery('##{pager_id}')".to_json_var }]
 
-    options = {:on_document_ready => true }
-    expected = expected_grid(grid_id, pager_id, options)
-    assert_equal(expected, @template.jqgrid(grid_id, options, grid_options))
+    options   = {:on_document_ready => true }
+    expected  = expected_grid(grid_id, pager_id, options)
+    assert_equal(expected, @template.jqgrid_api(grid_id, grid_options, options))
 
-    options = {:on_document_ready => true, :html_tags => true }
-    expected = expected_grid(grid_id, pager_id, options)
-    assert_equal(expected, @template.jqgrid(grid_id, options, grid_options))
+    options   = {:on_document_ready => true }
+    expected  = expected_grid(grid_id, pager_id, options)
+    assert_equal(expected, @template.jqgrid_api(grid_id, grid_options, options))
   end
 
   def expected_grid grid_id, pager_id, options
-    expected = ''
-    expected << '<table id="'+grid_id+'"></table>' + "\n" if options[:html_tags]
-    expected << '<div id="'+pager_id+'"></div>' + "\n" if options[:html_tags]
-    expected << '<script>' + "\n"
+
+    options[:script_tags] ||= true
 
     js =  'jQuery(document).ready(function() {
             jQuery("#' + grid_id + '").jqGrid({
               "pager":jQuery(\'#' + pager_id + '\')
             });
           });'
-    expected << js.gsub(/\n\s+/, '') + "\n"
-    expected << '</script>'
+    js.gsub!(/\n\s+/, '')
+    js = "<script>\n#{js}\n</script>" if options[:script_tags]
+    js
 
   end
 
   def test_jqgrid_nav_options
     @template = MockView.new
 
-    grid_id = 'grid_id'
-    pager_id = 'pager_id'
-    grid_options = {:pager => "##{pager_id}"}
-    options = {:on_document_ready => true, :html_tags => true}
-    nav_items = {:del => true}
-    del_config = {:closeOnEscape => true}
-
-    expected = '<table id="'+grid_id+'"></table>' + "\n"
-    expected << '<div id="'+pager_id+'"></div>' + "\n"
-    expected << "<script>" + "\n"
-    str =  'jQuery("#'+grid_id+'").jqGrid({"pager":"#'+pager_id+'"});'
-    str << 'jQuery("#'+grid_id+'").jqGrid("navGrid", "#'+pager_id+'", {"del":true}, {}, {}, {"closeOnEscape":true});'
-    expected << "jQuery(document).ready(function() {#{str}});" + "\n"
+    grid_id       = 'grid_id'
+    pager_id      = 'pager_id'
+    grid_options  = {:pager => "##{pager_id}"}
+    options       = {:on_document_ready => true, :script_tags => true}
+
+    expected  = "<script>" + "\n"
+    str       =   'jQuery("#'+grid_id+'").jqGrid({"pager":"#'+pager_id+'"}).jqGrid("navGrid", "#'+pager_id+'", {"del":true}, {}, {}, {"closeOnEscape":true});'
+    expected <<   "jQuery(document).ready(function() {#{str}});" + "\n"
     expected << "</script>"
 
-    assert_equal(expected, @template.jqgrid(grid_id,options,grid_options,nav_items,nil,nil,del_config))
+    assert_equal(expected, @template.jqgrid_api(grid_id, [grid_options], [:navGrid, "##{pager_id}", {:del => true }, {}, {}, {:closeOnEscape => true}], options))
   end
 
-  def testi_pager_id_from_options
+  def test_pager_id_from_options
     @template = MockView.new
 
     assert_equal 'my_pager_div', @template.send(:pager_id_from_options, {:pager => "jQuery('#my_pager_div')"})
@@ -86,5 +78,17 @@ class JqgridsHelperTest < Test::Unit::TestCase
     assert_equal 'my_pager_div', @template.send(:pager_id_from_options, {:pager => "my_pager_div"})
   end
 
+  def test_chained_functions
+    @template = MockView.new
+    div_id = 'my_grid'
+    functions = [
+      [:navButtonAdd, '#pager', { :caption => 'Add'}],
+      [: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})
+
+  end
 
 end

metadata

@@ -1,13 +1,12 @@
 --- !ruby/object:Gem::Specification 
 name: jqgrid_for_rails
 version: !ruby/object:Gem::Version 
-  hash: 23
   prerelease: false
   segments: 
+  - 1
   - 0
-  - 2
   - 0
-  version: 0.2.0
+  version: 1.0.0
 platform: ruby
 authors: 
 - Juan Manuel Cuello
@@ -15,7 +14,7 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-01-25 00:00:00 -03:00
+date: 2011-01-30 00:00:00 -03:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
@@ -26,7 +25,6 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        hash: 3
         segments: 
         - 0
         version: "0"
@@ -78,7 +76,6 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"
@@ -87,7 +84,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
   requirements: 
   - - ">="
     - !ruby/object:Gem::Version 
-      hash: 3
       segments: 
       - 0
       version: "0"