A long-lived project that still receives updates
The library allows you to easily build datagrid aka data tables with sortable columns and filters
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
 Dependencies

Runtime

>= 6.1
 Project Readme

Datagrid

Build Status

FOSSA Status

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

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

ORM Support

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

Create an issue if you want more.

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

  • Readme - this read-me for basic information.
  • Wiki - general reference on how to use the gem.
  • Rdoc - API reference.

Live Demo

Datagrid DEMO application is available live! Demo source code.

Example

In order to create a grid:

class UsersGrid

  include Datagrid

  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 partials

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

rake datagrid:copy_partials

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

FOSSA Status