datagrid

Datagrid

Datagrid Version 2.0.0 is here.

Migration Guide.

A really mighty and flexible ruby library that generates reports including admin panels, analytics and data browsers:

• Filtering
• Columns
• Sort order
• Localization
• Export to CSV

ORM Support

• ActiveRecord
• Mongoid
• MongoMapper
• Sequel
• Array (in-memory data of smaller scale)

Datagrid Philosophy

1. Expressive DSL complements OOD instead of replacing it.
2. Extensible in every way while providing a lot of defaults.
3. If your ORM supports that, datagrid also supports that!

Documentation

• Rdoc - full API reference
• Scope - working with datagrid scope
• Columns - definging datagrid columns
• Filters - defining datagrid filters
• Frontend - building a frontend
• Configuration - configuring the gem

Live Demo

Datagrid DEMO application is available live! Demo source code.

Example

In order to create a grid:

class UsersGrid < Datagrid::Base

  scope do
    User.includes(:group)
  end

  filter(:category, :enum, select: ["first", "second"])
  filter(:disabled, :xboolean)
  filter(:group_id, :integer, multiple: true)
  filter(:logins_count, :integer, range: true)
  filter(:group_name, :string, header: "Group") do |value|
    self.joins(:group).where(groups: {name: value})
  end

  column(:name)
  column(:group, order: -> { joins(:group).order(groups: :name) }) do |user|
    user.name
  end
  column(:active, header: "Activated") do |user|
    !user.disabled
  end

end

Basic grid api:

report = UsersGrid.new(
  group_id: [1,2],
  logins_count: [1, nil],
  category: "first",
  order: :group,
  descending: true
)

report.assets # => Array of User instances:
              # SELECT * FROM users WHERE users.group_id in (1,2) AND
              #   users.logins_count >= 1 AND
              #   users.category = 'first'
              # ORDER BY groups.name DESC

report.header # => ["Name", "Group", "Activated"]
report.rows   # => [
              #      ["Steve", "Spammers", false],
              #      [ "John", "Spoilers", false],
              #      ["Berry", "Good people", true]
              #    ]
report.data   # => [ header, *rows]

report.to_csv # => Yes, it is

Grid DSL

In order to create a report, you need to define:

• scope of objects to look through
• filters that will be used to filter data
• columns that should be displayed and sortable (if possible)

Scope

Default scope of objects to filter and display. In common case it is ActiveRecord::Base (or any other supported ORM) subclass with some generic scopes like:

scope do
  User.includes(:group)
end

More about scope

Filters

Each filter definition consists of:

• name of the filter
• type that will be used for value typecast
• conditions block that applies to defined scope
• additional options

Datagrid supports different type of filters including:

• text
• integer
• float
• date
• datetime
• boolean
• xboolean - the select of "yes", "no" and any
• enum - selection of the given values
• string
• dynamic - build dynamic SQL condition

More about filters

Columns

Each column is represented by name and code block to calculate the value.

column(:activated, header: "Active", order: "activated", after: :name) do
  self.activated?
end

Some formatting options are also available. Each column is sortable.

More about columns

Front end

Using Generator

Datagrid has a builtin generator:

rails g datagrid:scaffold skills

That gives you some code to play with out of the box:

create  app/grids/skills_grid.rb
create  app/controllers/skills_controller.rb
create  app/views/skills/index.html.erb
route  resources :skills
insert  app/assets/stylesheet/application.css

Customize Built-in views

In order to get a control on datagrid built-in views run:

rails g datagrid::views

Advanced frontend

All advanced frontend things are described in:

Frontend section on wiki

Questions & Issues

If you have a question of any kind, just make an issue and describe your problem in details.

Contribution

If you are interested in contributing to this project, please follow the instructions here.

Self-Promotion

Like datagrid?

Follow the repository on GitHub.

Read author blog.

License