Datagrid
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
- Expressive DSL complements OOD instead of replacing it.
- Extensible in every way while providing a lot of defaults.
- 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
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
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.
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:
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.