Admin framework for Rails 5+
Godmin is an admin framework for Rails 5+. Use it to build dedicated admin sections for your apps, or stand alone admin apps such as internal tools. It has support for common features such as scoping, filtering and performing batch actions on your models. Check out the demo app and its source code to get a feel for how it works.
Godmin differs from tools like ActiveAdmin and RailsAdmin in how admin sections are created. Rather than being DSL-based, Godmin is a set of opt-in modules and helpers that can be applied to regular Rails apps and engines. An admin section built with Godmin is just that, a regular Rails app or Rails engine, with regular routes, controllers and views. That means there is less to learn, because you already know most of it, and fewer constraints on what you can do. After all, administrators are users too, and what better way to provide them with a tailor made experience than building them a Rails app?
Godmin supports two common admin scenarios:
If you want to set up an example app that you can play around with, run the following:
rails new sandbox --skip-spring -m https://raw.githubusercontent.com/varvet/godmin/master/template.rb
Use for admin-only applications, or for architectures where the admin lives in its own app. E.g. you want to access the admin section at localhost:3000.
Add the gem to the application's Gemfile:
gem "godmin"
Bundle, then run the install generator:
$ bundle install
$ bin/rails generate godmin:install
Godmin should be up and running at localhost:3000.
Use when the admin is part of the same codebase as the main application. E.g. you want to access the admin section at localhost:3000/admin.
Generate a mountable engine:
$ bin/rails plugin new admin --mountable
Add the engine to the application's Gemfile:
gem "admin", path: "admin"
Mount the engine in the application's config/routes.rb:
mount Admin::Engine, at: "admin"
Add the gem to the engine's gemspec, admin/admin.gemspec:
s.add_dependency "godmin", "~> x.x.x"
Bundle, then run the install generator within the scope of the engine, i.e. note the leading admin/:
$ bundle install
$ admin/bin/rails generate godmin:install
Godmin should be up and running at localhost:3000/admin
Installing Godmin does a number of things to the Rails application.
The application controller is modified as such:
class ApplicationController
If Godmin was installed inside an engine, it creates a model class:
module Admin
class Article { [["News", 1], ["Posts", 2]] }
When specifying a collection of ActiveRecords, two additional parameters, option_text and option_value can be specified. They default to to_s and id respectively.
filter :category, as: :select, collection: -> { Category.all }, option_text: "title"
Batch actions can be created as follows:
class ArticleService
include Godmin::Resources::ResourceService
batch_action :publish
batch_action :unpublish
batch_action :destroy, confirm: true
def batch_action_publish(resources)
resources.each(&:publish!)
end
end
In addition, batch actions can be defined per scope using only and except:
batch_action :publish, only: [:unpublished]
batch_action :unpublish, only: [:published]
If you wish to implement your own redirect after a batch action, it needs to be implemented in the controller:
class ArticlesController
Append stuff here
If you wish to customize the content of a table column, you can place a partial under app/views/{resource}/columns/{column_name}.html.erb, e.g. app/views/articles/columns/_title.html.erb. The resource is available to the partial through the resource variable.
The full list of templates and partials that can be overridden can be found here.
Oftentimes, the default form provided by Godmin doesn't cut it. The godmin/resource/_form.html.erb partial is therefore one of the most common to override per resource.
Godmin comes with its own FormBuilder that automatically generates bootstrapped markup. It is based on the Rails Bootstrap Forms FormBuilder, and all its methods are directly available. In addition it has a few convenience methods that can be leveraged.
The input method will automatically detect the type of field from the database and generate an appropriate form field:
form_for @resource do |f|
f.input :attribute
end
Godmin comes with built in view helpers for generating the navbar.
The navbar_item helper generates a link in the navbar. It can be used in a number of different ways.
# Links to the index page of the article resource
navbar_item Article
# Links to a custom path with a custom link text
navbar_item Article, articles_path(scope: :published) do
"Published articles"
end
# Links to a custom path with a custom link text without specifying resource
navbar_item "Some text", some_path
The show option can be passed a proc that evaluates to true or false. This is used to control if the link should be shown or not. By default it checks against the resource policy object if authorization is enabled.
navbar_item Article, show: -> { show? }
The icon option can be passed a glyphicon:
navbar_item Article, icon: "book"
The navbar_dropdown and navbar_divider helpers can be used to build dropdown menus.
navbar_dropdown "Multiple things" do
navbar_item Article
navbar_item Comment
navbar_divider
navbar_item User
end
Multiple authentication scenarios are supported. Godmin comes with a lightweight built in authentication solution that can be used to sign in to the admin section via the admin interface. In addition, when running an admin engine, it is possible to set up a shared authentication solution so that administrators can sign in via the main app.
This example uses the built in authentication solution. Authentication is isolated to the admin section and administrators sign in via the admin interface.
Godmin comes with a generator that creates an admin user model and enables the built in authentication:
$ bin/rails generate godmin:authentication
$ bin/rake db:migrate
Please note: when installing to an admin engine, the migration needs to be moved to the main app before it can be found by db:migrate. Rails has a solution in place for this:
$ admin/bin/rails generate godmin:authentication
$ bin/rake admin:install:migrations
$ bin/rake db:migrate
A model is generated:
class AdminUser Create: foobar...
If the field is added post page render, it can be initialized manually:
Godmin.SelectBoxes.initializeSelectBox($el);
Additional options can be passed down to selectize:
Godmin.SelectBoxes.initializeSelectBox($el, {
create: true
});
Some additional features are available as plugins:
https://github.com/varvet/godmin/graphs/contributors
Licensed under the MIT license. See the separate MIT-LICENSE file.
No open issues yet, or sync has not completed.