File: README — Documentation for jqgrid_for

JqgridForRails

This is a simple plug-in to create a JqGrid 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 create the grid using javascript but in Ruby. The code should follow the jqgrid api definition.

For example, to get this java script code:

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

As a gem:

$ gem install jqgrid_for_rails

As a plugin:

$ rails plugin install git://github.com/Juanmcuello/jqgrid_for_rails.git

Examples

There is an example application at:

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_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

  include JqgridsHelper

  def invoices_jqgrid

    grid = [{
      :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!');}".to_json_var
    }]

    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>

<script>
  jQuery("#invoices_list").jqGrid({
    "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 in the view:

<% content_for :head do %>
  <%= raw(invoices_jqgrid) %>
<% end %>

Don’t forget to include the jquery and jqgrid javascript and stylesheet files!

col_model_for_jqgrid

This helper 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 you 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_for_jqgrid(['Inv No','Date']),
  :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

Controllers

There are convenient methods available in the controllers

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.

In the controller:

# 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

Juan Manuel Cuello (github.com/Juanmcuello)