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)

Status¶ ↑

Active Admin is very young. Although the code is well tested and is being used in production, the project is under heavy development. Once we get it to a point that has a relatively stable api, we will begin numbered releases starting with a 0.1 release.

Installation (Rails 3)¶ ↑

Active Admin is released as a Gem. Installing the gem deals with all its dependencies, however WillPaginate seems to have some Rails 3 issues still. For now:

Add the following to your Gemfile:

gem 'will_paginate',  :git => "git://github.com/mislav/will_paginate.git", :branch => 'rails3'
gem 'activeadmin'

Then, run the installer:

rails generate active_admin:install

This will create an initializer which is used for configuring defaults used by Active Admin as well as a new folder at app/admin to put all your admin configurations. Note: All ruby files in the Active Admin load path get loaded into the rails application.

Usage¶ ↑

Let’s build up an example using a Post model and the provided admin generator.

rails generate active_admin:resource post

That’s all you need to get a full CRUD, beautiful administration interface!

The generator will create a new file app/admin/posts.rb that will look like the following:

ActiveAdmin.register Post

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:

ActiveAdmin.register Post do

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

end

Or you can pass them in individually:

ActiveAdmin.register Post do

  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.

ActiveAdmin.register Post do

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

end

The block gets called once for each resource in the collection. The resource gets passed into the block as an argument.

Sorting¶ ↑

The index views in Active Admin include sorting by default.

ActiveAdmin.register Post do

  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){|post| 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¶ ↑

Active Admin gives complete control over the output of the form by creating a thin DSL on top of the fabulous DSL created by Formtastic (github.com/justinfrench/formtastic).

ActiveAdmin.register Post do

  form do |f|
    f.inputs "Details" do
      f.input :title
      f.input :published_at, :label => "Publish Post At"
      f.input :category
    end
    f.inputs "Content" do
      f.input :body
    end
    f.buttons
  end

end

Please view the documentation for Formtastic to see all the wonderful things you can do: github.com/justinfrench/formtastic

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¶ ↑

• Greg Bell github.com/gregbell

• Philippe Creux github.com/pcreux

• Sam Vincent github.com/samvincent

• Matt Vague github.com/mattvague

• Dan Kubb github.com/dkubb

Roadmap & Issue Tracking¶ ↑

We are using the awesome Lighthouse ticketing system. The project can be found at: activeadmin.lighthouseapp.com

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.