= 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.

http://travis-ci.org/gregbell/active_admin.png

== 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 <tt>app/admin</tt> to put all your admin configurations.

Migrate your db and start the server:

  $> rake db:migrate
  $> rails server

Visit http://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 <tt>app/admin/my_model_names.rb</tt> 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
<tt>config/initializers/active_admin.rb</tt>. 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"

== Customize The Resource

=== Rename the Resource

By default, any references to the resource (menu, routes, buttons, etc) in the
interface will use the name of the class. You can rename the resource by using
the <tt>:as</tt> option.

  ActiveAdmin.register Post, :as => "Article"

The resource will then be available as /admin/articles

=== Customize the Navigation

The resource will be displayed in the global navigation by default.

To disable the resource from being displayed in the global navigation:

  ActiveAdmin.register Post do
    menu false
  end

To change the name of the label in the menu:

  ActiveAdmin.register Post do
    menu :label => "My Posts"
  end

To add the menu as a child of another menu:

  ActiveAdmin.register Post do
    menu :parent => "Blog"
  end

This will create the menu item if it doesn't exist yet.

== 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

By default the index screen includes a "Filters" sidebar on the right hand side
with a filter for each attribute of the registered model. You can customize the
filters that are displayed as well as the type of widgets they use.

To display a filter for an attribute, use the filter method

  ActiveAdmin.register Post do
    filter :title
  end

Out of the box, Active Admin supports the following filter types:

* *:string* - A search field
* *:date_range* - A start and end date field with calendar inputs
* *:numeric* - A drop down for selecting "Equal To", "Greater Than" or "Less
  Than" and an input for a value.
* *:select* - A drop down which filters based on a selected item in a collection
  or all.
* *:check_boxes* - A list of check boxes users can turn on and off to filter

By default, Active Admin will pick the most relevant filter based on the
attribute type. You can force the type by passing the :as option.

  filter :author, :as => :check_boxes

The :check_boxes and :select types accept options for the collection. By default
it attempts to create a collection based on an association. But you can pass in
the collection as a proc to be called at render time.

  # Will call available
  filter :author, :as => :check_boxes, :collection => proc { Author.all }

You can change the filter label by passing a label option:

  filter :author, :label => 'Author'

By default, Active Admin will try to use ActiveModel I18n to determine the label.

== Customizing the CSV format

Customizing the CSV format is as simple as customizing the index page.

  csv do
    column :name
    column("Author") { |post| post.author.full_name }
  end
>>>>>>> master

== 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 (http://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:
http://github.com/justinfrench/formtastic


== Customizing the Show Screen

Customizing the show screen is as simple as implementing the show block:

  ActiveAdmin.register Post do
    show do
      h3 post.title
      div do
        simple_format post.body
      end
    end
  end

The show block is rendered within the context of the view and uses the Arbre HTML DSL. You
can also render a partial at any point.

  ActiveAdmin.register Post do
    show do
      # renders app/views/admin/posts/_some_partial.html.erb
      render "some_partial"
    end
  end


== Sidebar Sections

To add a sidebar section to all the screen within a section, use the sidebar method:

  sidebar :help do
    "Need help? Email us at help@example.com"
  end

This will generate a sidebar section on each screen of the resource. With the block as
the contents of the section. The first argument is the section title.

You can also use Arbre syntax to define the content.

  sidebar :help do
    ul do
      li "Second List First Item"
      li "Second List Second Item"
    end
  end

Sidebar sections can be rendered on a specific action by using the :only or :except
options.

  sidebar :help, :only => :index do
    "Need help? Email us at help@example.com"
  end

If you only pass a symbol, Active Admin will attempt to locate a partial to render.

  # Will render app/views/admin/posts/_help_sidebar.html.erb
  sidebar :help

Or you can pass your own custom partial to render.

  sidebar :help, :partial => "custom_help_partial"

== Internationalization (I18n)

To internationalize Active Admin or to change default strings, you can copy
lib/active_admin/locales/en.yml to your application config/locales directory and
change its content. You can contribute to the project with your translations to!

== 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
Kaminari::
  Pagination for rails apps
Iconic Icons::
  Excellent SVG icon set designed by P.J. Onori: http://somerandomdude.com/projects/iconic


== Contributors

* Greg Bell       http://github.com/gregbell
* Philippe Creux  http://github.com/pcreux
* Sam Vincent     http://github.com/samvincent
* Matt Vague      http://github.com/mattvague
* Dan Kubb        http://github.com/dkubb
* Sam Reh         http://github.com/samuelreh


== 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 (c) 2010 Greg Bell, VersaPay Corporation. See LICENSE for details.