Datagrid
¶ ↑
Datagrid
Version 2.0.0 is here.
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¶ ↑
-
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¶ ↑
-
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
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 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:
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.