Skip to content

Latest commit

 

History

History
221 lines (155 loc) · 5.35 KB

README.md

File metadata and controls

221 lines (155 loc) · 5.35 KB
Raw

Datagrid

Datagrid Version 2.0.0 is here.

Migration Guide.

Build Status

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

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 documentation

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