Admini is a minimal administration framework for Ruby on Rails application.
The core feature is just provides CRUD actions as Active Support's Concern module. So you can implement administration page as usual.
Admini solves the same problem as ActiveAdmin, RailsAdmin and Administrate. Admini is the simplest framework, so you can create administration page according to the Rails way.
You can try an administration page built with Admini at following link. The code of the demo can be found here.
Add this line to your application's Gemfile:
gem 'admini'
And then execute:
$ bundle
If the namespace of your administration page is :admin
, you probably create Admin::ApplicationController
like this:
class Admin::ApplicationController < ActionController::Base
protect_from_forgery with: :exception
# If you use Devise:
# before_action :authenticate_user!
end
There's no code related to Admini. You can implement as you like, such as an authentication.
Now everything is ready to create administration page. For example, to create the page manages Post model, you have to do the following steps:
- Create
Admin::PostsController
and includeAdmini::Resources
- Add routing
The example codes is below:
class Admin::PostsController < Admin::ApplicationController
include Admini::Resources
end
namespace :admin do
resources :posts
end
That's it, and now you can take action index
, new
, create
, show
, edit
, update
, destroy
the posts at /admin/posts
.
The items rendering on index
, new
, show
and edit
can customize using #xxx_attributes
.
If you define following methods to controller, the items have changed:
#index_attributes
#show_attributes
(default:#index_attributes
)#new_attributes
#edit_attributes
(default:#new_attributes
)
Examples:
class Admin::PostsController < Admin::ApplicationController
include Admini::Resources
private
def index_attributes
%i(id title status created_at)
end
def show_attributes
%i(id title status created_at content)
end
def new_attributes
%i(title status content)
end
end
The items rendering text on index
and show
are also customizable as you like.
If you define #render_xxx
on your controller, Admini renders text according to the method.
Here is an example that renders a title with link to post instead of just title.
class Admin::PostsController < Admin::ApplicationController
include Admini::Resources
private
def render_title(resource)
path = case resource.status
when 'draft'
preview_post_path(resource, token: resource.preview_token)
else
post_path(resource)
end
view_context.link_to resource.title, path
end
end
In the same way, a method name to customize the content
is #render_content
, or created_at
is #render_created_at
.
If you want to enable the search form, you should just define #search_attributes
on your controller.
Following examples enable the search form searched by title
and content
.
class Admin::PostsController < Admin::ApplicationController
include Admini::Resources
private
def search_attributes
%i(title content)
end
end
Enum is treated as Integer by database, so enum form has created as text field by default.
If you want to show the form as select box, you should define #enum_attributes
.
class Admin::PostsController < Admin::ApplicationController
include Admini::Resources
private
def enum_attributes
%i(status)
end
end
Often we want to override CRUD actions, especially create
and update
.
To do this, just define #create
or #update
on your controller.
If you want to delegate to super
defined by Admini, you should call #super
on the action.
class Admin::PostsController < Admin::ApplicationController
include Admini::Resources
def create
@resource.user = current_user
super
end
end
You can simply authorize user using CanCanCan, Pundit or your own code.
When you define the following methods on your controller, Admini authorizes user with it, and raise Admini::AuthorizationError
if user has not authorized.
#can_create?
#can_read?
#can_update?
#can_delete?
Examples using CanCanCan:
class Admin::PostsController < Admin::ApplicationController
include Admini::Resources
private
def can_create?
can? :create, Post
end
end
Also you can define custom error handler.
This is realized by to define #authorization_error
on your Admin::ApplicationController
.
class Admin::ApplicationController < ActionController::Base
private
def authorization_error
puts 'Authorization error'
end
end
Admini doesn't apply any styles to administration pages by default. Because Admini should be minimal. If you want to apply basic style created by Admini, you should require the stylesheet.
app/assets/stylesheets/admini/application.css
:
/*
*= require admini/default
*/
Needless to say, you can write your own styles here as you like.
Admini is minimal, so the links to pages will not added automatically. The default view generated by Admini doesn't have any links like this.
However, you can override header menu by editing app/views/admini/layouts/_header.html.erb
.
Examples:
<div class="header">
<div class="container">
<%= link_to 'Admin', admin_root_path, class: 'header-title' %>
<%= link_to 'Posts', admin_posts_path %>
<%= link_to 'Users', admin_users_path %>
<div class="right">
<%= link_to 'Logout', destroy_user_session_path, method: :delete %>
</div>
</div>
</div>
The view has rendered with a common views. If you want to implement original views, you should place your own views according to Rails convention.
For example, to customize the view of admin/posts#show
, you should create app/views/admin/posts/show.html.erb
.
<h1>admin/posts#show</h1>
In the same way, you can override all views, including application.html.erb
, _header.html.erb
, _nav.html.erb
.
Admini sets [:admin, @resource]
as the namespace of form object by default.
This is because generally we adopt :admin
as administration page's namespace.
If your administration page has a different namespace like :editor
, you should define #resource_object
on your Editor::ApplicationController
.
class Editor::ApplicationController < ActionController::Base
private
def resource_object
[:editor, resource]
end
end
Admini depends on Kaminari as paginater, and it paginates per 25
items.
You can override this number by #paginates_per
method.
class Admin::ApplicationController < ActionController::Base
private
def paginates_per
10
end
end
Feel free to ask me in Issues or author's twitter.
- Fork it ( https://github.com/kami-zh/admini/fork )
- Create your feature branch (git checkout -b my-new-feature)
- Commit your changes (git commit -am 'Add some feature')
- Push to the branch (git push origin my-new-feature)
- Create a new Pull Request
The gem is available as open source under the terms of the MIT License.