Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

The administration framework for Ruby on Rails applications.

tag: v0.2.0

Fetching latest commit…

Octocat-spinner-32-eaf2f5

Cannot retrieve the latest commit at this time

Octocat-spinner-32 features
Octocat-spinner-32 lib
Octocat-spinner-32 spec
Octocat-spinner-32 .document
Octocat-spinner-32 .gitignore
Octocat-spinner-32 CHANGELOG.rdoc
Octocat-spinner-32 Gemfile
Octocat-spinner-32 LICENSE
Octocat-spinner-32 README.rdoc
Octocat-spinner-32 Rakefile
Octocat-spinner-32 activeadmin.gemspec
Octocat-spinner-32 cucumber.yml
README.rdoc

Active Admin

Active Admin is a framework for creating administration style interfaces. It abstracts common business application patterns to make it simple for developers to implement beautiful and elegant interfaces with very little effort.

Goals

  1. Allow developers to quickly create gorgeous administration interfaces <strong>(Not Just CRUD)</strong>

  2. Build a DSL for developers and an interface for businesses.

  3. Ensure that developers can easily customize every nook and cranny of the interface.

  4. Build common interfaces as shareable gems so that the entire community benefits.

Getting Started

Active Admin is released as a Ruby Gem. The gem is to be installed within a Ruby on Rails 3 application. To install, simply add the following to your Gemfile:

# Gemfile
gem 'activeadmin'

After updating your bundle, run the installer

$> rails generate active_admin:install

The installer creates an initializer used for configuring defaults used by Active Admin as well as a new folder at app/admin to put all your admin configurations.

Migrate your db and start the server:

$> rake db:migrate
$> rails server

Visit localhost:3000/admin and log in using:

  • User: admin@example.com

  • Password: password

Voila! You're on your brand new Active Admin dashboard.

To register your first model, run:

$> rails generate active_admin:resource [MyModelName]

This creates a file at app/admin/my_model_names.rb for configuring the resource. Refresh your web browser to see the interface.

To learn how to further configure your admin section, keep on reading!

General Configuration

Admin Users

By default Active Admin will include Devise and create a new model called AdminUser. If you would like to use another name, you can pass it in to the installer through the user option:

$> rails generate active_admin:install UserClassName

If you don't want the generator to create any user classes:

$> rails generate active_admin:install --skip-users

Authentication

Active Admin requires two settings to authenticate and use the current user within your application. Both are set in config/initializers/active_admin.rb. By default they are setup for use with Devise and a model named AdminUser. If you chose a different model name, you will need to update these settings.

Set the method that controllers should call to authenticate the current user with:

# config/initializers/active_admin.rb
config.authentication_method = :authenticate_admin_user!

Set the method to call within the view to access the current admin user

# config/initializers/active_admin.rb
config.current_user_method = :current_admin_user

Both of these settings can be set to false to turn off authentication.

# Turn off authentication all together
config.authentication_method = false
config.current_user_method   = false

Site Title

You can update the title used for the site in the initializer also. By default it is set to the name of your Rails.application class name.

# config/initializers/active_admin.rb
config.site_title = "My Admin Site"

Customizing the Index Page

Filtering and listing resources is one of the most important tasks for administering a web application. Active Admin provides many different tools for you to build a compelling interface into your data for the admin staff.

Built in, Active Admin has the following index renderers:

  • Table: A table drawn with each row being a resource

  • Grid: A set of rows and columns each cell being a resource

  • Blocks: A set of rows (not tabular) each row being a resource

  • Blog: A title and body content, similar to a blog index

All index pages also support scopes, filters, pagination, action items, and sidebar sections.

Index as a Table

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.

Defining Columns

To display an attribute or a method on a resource, simply pass a symbol into the column method:

index do
  column :title
end

If the default title does not work for you, pass it as the first argument:

index do
  column "My Custom Title", :title
end

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.

The column method accepts a block as an argument which will then be rendered within the context of the view for each of the objects in the collection.

index do
  column "Title" do |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

When a column is generated from an Active Record attribute, the table is sortable by default. If you are creating a custom column, you may need to give Active Admin a hint for how to sort the table.

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.

index do
  column "Title", :sortable => :title do |post| 
    link_to post.title, admin_post_path(post)
  end
end

You can turn off sorting on any column by passing false:

index do
  column :title, :sortable => false
end

Showing and Hiding Columns

The entire index block is rendered within the context of the view, so you can easily do things that show or hide columns based on the current context.

For example, if you were using CanCan:

index do
  column :title, :sortable => false
  if can? :manage, Post
    column :some_secret_data
  end
end

Index as a Grid

Sometimes you want to display the index screen for a set of resources as a grid (possibly a grid of thumbnail images). To do so, use the :grid option for the index block.

index :as => :grid do |product|
  link_to(image_tag(product.image_path), admin_products_path(product))
end

The block is rendered within a cell in the grid once for each resource in the collection. The resource is passed into the block for you to use in the view.

You can customize the number of colums that are rendered using the columns option:

index :as => :grid, :columns => 5 do |product|
  link_to(image_tag(product.image_path), admin_products_path(product))
end

Index as a Block

If you want to fully customize the display of your resources on the index screen, Index as a Block allows you to render a block of content for each resource.

index :as => :block do |product|
  div :for => product do
    h2 auto_link(product.title)
    div do
      simple_format product.description
    end
  end
end

Index Filters

Index Scopes

Customizing 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

Customizing the Show Screen

Action Items

Sidebar Sections

The Dashboard

Custom Actions

Collection Actions

Member Actions

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.

Devise

User authentication is done using Devise

WillPaginate

Pagination for rails apps

Iconic Icons

Excellent SVG icon set designed by P.J. Onori: somerandomdude.com/projects/iconic

Contributors

Roadmap & Issue Tracking

We are using the awesome Github issues!

Note on Patches/Pull Requests

  • Fork the project.

  • Make your feature addition or bug fix on a new topic branch

  • Add specs and cukes 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.

Copyright

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

Something went wrong with that request. Please try again.