== SimpleAdmin
SimpleAdmin is a simple set of templates and controllers that can be used to quickly build out an admin section on your Rails site. It is heavily based on the popular {ActiveAdmin}[link:http://activeadmin.info/] gem from {Greg Bell}[link:https://twitter.com/#!/gregbell] and VersaPay (in fact, the default stylesheets, javascripts, and images come directly from the {ActiveAdmin project}[link:https://github.com/gregbell/active_admin] because they are awesome).
So why a new gem? ActiveAdmin has a lot of features and dependencies out of the box. These are great but are often more than you need, and unfortunately they create a lot of complexity in the underlying gem and integration. SimpleAdmin eschews much of that complexity and is instead a basic Rails engine. This makes debugging problems simpler as there are fewer dependencies, less meta-programming, and a smaller set of features.
== Getting started
In your Gemfile, include simple_admin and formtastic (and fastercsv if you are on an older version of Ruby):
gem "simple_admin"
gem "formtastic"
gem "fastercsv" # if Ruby < 1.9
Bundle install:
bundle
Generate out the configuration:
rails g simple_admin:install
Install the assets into your public folder so that they can be served by your web server instead of being served through rails.
rails g simple_admin:assets
Add any administration interfaces (for example, in app/admin/posts.rb):
SimpleAdmin.register :post do
end
Restart rails and check out your new admin interface.
== Customizing an interface
Although you could use the simple registration pattern above, you may need some more control. Within the register block you can override the defaults using the following commands:
The +before+ helper allows you to specify any +before_filter+ style logic. It requires a block which is executed in the context of the controller prior to the page being displayed:
SimpleAdmin.register :post do
before do
# You could use this instead of the default config option
require_admin
end
end
You can also specify to which actions the before block should be applied:
SimpleAdmin.register :post do
before :only => [:create, :destroy] do
require_admin
end
end
The +index+ helper controls the index display. If you don't include the index command then a default index page will be setup. If you do include it you can override the behavior. You can pass a title option to modify the default page title:
SimpleAdmin.register :post do
# Customizing the title on the page
index :title => 'Posts people have made'
end
The +index+ helper also accepts a block. Within the block you have access modify the default filters and attributes. If you don't include an attributes specification or a filters specification then the defaults will be used.
Within the +index+, +show+, and +form+ blocks, the attributes command works the same. It accepts either +except+ or +only+ as an option to limit the list of default attributes:
SimpleAdmin.register :post do
index do
# Customize what attributes show using except
attributes :except => [:id, :body]
end
end
SimpleAdmin.register :post do
index do
# Customize what attributes show using only
attributes :only => [:id, :title]
end
end
You can omit these options and instead include a block. Within the block you can call
Clearing the list of attributes allows you complete control over what shows. The +defaults+ helper is not used very often, but allows you to reset to the default list of attributes:
SimpleAdmin.register :post do
index do
attributes do
# No attributes
clear
# An attribute
attribute :title
# Add an attribute with some data
attribute :body, :title => "Post content" {|post| post.body.slice(60) }
end
end
end
The +attribute+ command allows you to add a new attribute (if you had called clear) or override an already included default (if you had not called clear, or had already specified an attribute). The attribute helper expects the attribute name (as a symbol), any options, and an optional block which will be evaluated at the time of display. The only options that are expected are +:title+ which controls the associated label or header and +:sortable+ which is only used within the index (and which can only be set to false).
SimpleAdmin.register :post do
index do
end
# The show section allows you to control the show page
show do
# Control which attributes are displayed
attributes :only => [:title, :body]
end
# The form section allows you to control the new and edit pages
form do
# Control which attributes can be modified
attributes do
clear
attribute :title
attribute :body
end
end
end
Within the index you can also specify +filters+, which work exactly like +attributes+ except that they control the search and filtering form on the right. You can also customize the filter by passing +:as+ and +:collection+ options.
SimpleAdmin.register :post do
index do
attributes do
# This is not necessary, attributes are defaulted automatically
defaults
end
filters do
# No filters
clear
# Add a filter for searching the title
filter :title
end
end
end
Finally, within +index+, +show+ and +form+ you can specify any number of +sidebar+ helpers. Sidebars require a block which is executed at the time of rendering:
SimpleAdmin.register :post do
index do
sidebar do
# Within index you have @collection, in other views you have @resource
your_post_stats_helper(@collection)
end
end
end
== Customizing the routes
When you generate simple_admin into your application a new mount point is automatically created:
mount SimpleAdmin::Engine => '/admin'
You can change this path however you see fit.
The available actions for each admin interface can also be customized:
SimpleAdmin.register :posts, :actions => [:index, :show] do
end
These will be directly reflected in the routes for the interface. If changed, you will need to restart your Rails server as the routes are generated at initialization. Available actions are:
You can also see the routes that are generated by your admin interfaces by running:
rake routes:simple_admin
== Configuration options
All of the configuration for SimpleAdmin happens within the +config/initializers/simple_admin.rb+ file that is generated when you run the generator.
The +require_user_method+ setting allows you to specify which controller method should be called before rendering any admin pages. There is no default for this method. If it is not present then simple_admin will not do any admin verification prior to performing its controller actions.
It is possible to check for admin status using application level before filters or even using the +before+ block within each individual admin interface registration.
To set this, specify the controller method you want called as a symbol:
config.require_user_method = :require_admin
The +current_user_method+ is used by simple_admin to determine if there is a logged in user. There is no default for this property. If it is not present, no logged in user method will be checked and user information will not be displayed in the header of admin forms.
To set this, specify the controller method you want called as a symbol:
config.current_user_method = :current_user
The +current_user_name_method+ is used by simple_admin to access the display name of the currently logged in user. There is no default for this property. If it is not present, any logged in user name will not be displayed in the header of admin forms.
To set this, specify the controller method you want called as a symbol:
config.current_user_name_method = :current_user_name
The +site_title+ is displayed in the header of admin pages. If empty this value defaults to +Rails.application.class.parent_name.titleize+:
config.site_title = "My Website"
The +default_per_page+ value allows you to control how many results appear on admin index pages. This value is fed into kaminari and is defaulted to 25 if not present:
config.default_per_page = 25
The +form_for_helper+ defaults to the +:semantic_form_for+ helper from formtastic. If you want to use another engine, like +simple_form+ you can change this property and the gem requirements. Note that the default styling from active_admin relies on formtastic output.
config.form_for_helper = :semantic_form_for
The +stylesheet+ and +javascript+ properties are used within the admin layout and are defaulted to the active_admin styles and scripts. You may want to override these styles, or simply use the asset pipeline instead of installing them to your public folder. These properties allow you to manage where the assets are stored (either within the default pipeline or no). By default, SimpleAdmin assumes you have run the asset generator (rails g simple_admin:assets) and that these files live within your public folder:
config.stylesheet = "/stylesheets/simple_admin/active_admin.css"
config.javascript = "/javascripts/simple_admin/active_admin.js"
== Testing
To run the specs you need to clone this repository, bundle, then generate the sample application:
rake sample
I went against the defaults from Rails 3.1 because one rake task is simpler, and this can target any rails version currently installed for testing. Plus, I use specs.
After that:
rake spec
== Contributors
== Acknowledgements
Special thanks to the ActiveAdmin team and Greg Bell ({@gregbell}[link:https://twitter.com/#!/gregbell]). I cribbed tons off ActiveAdmin, and used the default ActiveAdmin styles. This represents large portion of this gem.
Thanks also Nick Plante ({@zapnap}[link:https://twitter.com/#!/zapnap]) for helping get the specs organized in the engine and for fighting through the refactoring with me.
Thanks also to Ryan Bigg ({@ryanbigg}[link:https://twitter.com/#!/ryanbigg]) for his Forem project and help in IRC.