Permalink
Find file
Fetching contributors…
Cannot retrieve contributors at this time
158 lines (99 sloc) 4.99 KB

Active Admin

Active Admin is a tool to facilitate the generation of administration style interfaces.

Goals

Although Active Admin is very young in its development cycle, here are its current goals:

  1. Build a toolset to quickly create template-able administration interfaces

  2. Allow the toolset to be entirely customizable (ie: we use standard rails coding practices which can be overridden at any point)

  3. Design an interface which looks great!

  4. Build administration interfaces for common rails plugins as gems and share with the community (ie: devise admin)

Installation (Rails 3)

Add the following to your Gemfile:

gem 'formtastic',     :git => "git://github.com/justinfrench/formtastic.git", :branch => 'rails3'
gem 'will_paginate',  :git => "git://github.com/mislav/will_paginate.git", :branch => 'rails3'
gem 'active_admin',   :git => "git://github.com/gregbell/active_admin.git"

Usage

Currently, to use the features of Active Admin, create a controller for which you would like administer a model and subclass the ActiveAdmin::AdminController. Let's build up an example using a Post model.

# /app/controllers/admin/posts_controller.rb
class Admin::PostsController < ActiveAdmin::AdminController
end

That's all you need to get a full CRUD, beautiful administration interfaces.

Customize the Index Page

By default, the index page is a table with each of the models content columns and links to show, edit and delete the object. There are many ways to customize what gets displayed:

Simple Columns

If all you need to do is change the columns which get displayed, you can do so by passing them to the columns method:

class Admin::PostsController < ActiveAdmin::AdminController

  index do |display|
    display.columns :title, :comments_count, :created_at
  end

end

Or you can pass them in individually:

class Admin::PostsController < ActiveAdmin::AdminController

  index do |display|

    # This will title the column 'Title' and call the #title method on each object
    display.column :title

    # This will title the column 'How many comments?' and call the #comments_count method on each object
    display.column 'How many comments?', :comments_count

    # You can add methods to the table builder which builds common things (ie: selectable checkboxes)
    display.default_actions

  end

end

Advanced Columns

Sometimes calling methods just isn't enough and you need to write some view specific code. For example, say we wanted a colum called Title which holds a link to the posts admin screen.

You can pass a block to a column which will then be rendered within the context of the view for each of the objects in the collection.

class Admin::PostsController < ActiveAdmin::AdminController

  index do |display|
    display.column("Title"){ link_to @post.title, admin_post_path(@post) }
  end

end

The block has access to an instance variable named after the model which holds the current object while iterating over the collection. You can also access the current object using the #resource method and the @resource instance variable

Sorting

The index views in Active Admin include sorting by default.

class Admin::PostsController < ActiveAdmin::AdminController

  index do |display|

    # A column created by a method call assumes its sortable
    display.column :id

    # If a column is defined using a block, you must pass the key to turn on sorting. The key
    # is the attribute which gets used to sort objects using Active Record.
    display.column("Title", :sortable => :title){ link_to @post.title, admin_post_path(@post) }

    # Turn off sorting by passing false
    display.column :do_not_sort_me, :sortable => false

  end

end

Customize the Form

Tools Being Used

We believe strongly in not writing code unless we have to, so Active Admin is built using many other open source projects:

InheritedResources

Inherited Resources speeds up development by making your controllers inherit all restful actions so you just have to focus on what is important.

InheritedViews

Inherited Views is a thin addition to Inherited Resources which adds in html views to the mix

Formtastic

A DSL for semantically building amazing forms.

WillPaginate

Pagination for rails apps

Contributors

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix.

  • Add tests for it. This is important so I don't break it in a future version unintentionally.

  • Commit, do not mess with rakefile, version, or history. (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)

  • Send me a pull request. Bonus points for topic branches.

Copyright

Copyright © 2010 Greg Bell, VersaPay Corporation. See LICENSE for details.