Frontend

Description

Datagrid includes helpers and form builder for easy front end generation. If you need to build full featured custom GUI you should create your templates manually with the help of Columns API.

Controller and Routing

Grids in most cases are not resources and in most cases you need only one action to handle creating, display and editing report:

map.resources :my_reports, :only => [:index]

In this case GET method should be always used in a form. And controller will look damn simple:

class MyReportsController < ApplicationController
  def index
    @report = MyReport.new(params[:my_report])
  end
end

Form builder

In order to create a form you can use all set of rails built-in tools:

(haml for readability)

- form_for UserGrid.new do |form|
  %div
    = f.label :name
    = f.text_field :name

In addition Datagrid provides you magic helper to generate input/select for corresponding filter type:

%div
  = f.datagrid_label :name
  = f.datagrid_filter :name        # => <input name="grid[name]" type="text"/>

%div
  = f.datagrid_label :category_id
  = f.datagrid_filter :category_id # => <select name="grid[category_id]">....</select>

The easiest way to create a report form:

- form_for @report, :html => {:method => :get} do |f|
  - @report.filters.each do |filter|
    %div
      = f.datagrid_label filter
      = f.datagrid_filter filter
  = f.submit

See also localization section of Filters

Datagrid table

There is a simple helper set of helpers that allows you display report. The most common way of doing it is (require any pagination gem, will_paginate gem is used as an example):

- assets = @report.assets.paginate(:page => params[:page])

%div== Total #{assets.total}
= datagrid_table(@report, assets)
= will_paginate assets

Supported options:

• :html - hash of attributes for <table> tag
• :order - If false do not generate ordering controlls. Default: true.
• :cycle - Used as arguments for cycle for each row. Default: false. Example: :cycle => ["odd", "even"].

This will create generic table from paginated assets with all defined columns and sorting controlls.

See also Localization section of Columns

Pagination

Datagrid is abstract from pagination.

It has only one pagination-sensitive helper: datagrid_table.

In order to avoid pagination dependency, do the following in your controllers:

@grid = MyGrid.new(params[:grid])
# WillPaginate
@assets = @grid.assets.paginate(:page => params[:page], :per_page => 20)
# Kaminari
@assets = @grid.assets.per(10).page(params[:page]).
# OMG paginate
@assets = @grid.assets.paginate_to_the_max

And then render paginated collection:

<%= datagrid_table(@grid, @assets, options) %>

Table customization

If You need serious customization of datagrid <table> and HTML Columns doesn't help(see Column Value section in Columns), you can customize datagrid internal views by running:

rake datagrid:copy_partials

This will create the following files in your rails root directory:

|~app/
| `~views/
|   `~datagrid/
|     |-_head.html.erb
|     |-_row.html.erb
|     `-_table.html.erb

Now You are able to customize whatever You want.