Administrate Documentation

Administrate is a framework for creating flexible, powerful admin dashboards in Ruby on Rails. It provides clean interfaces for users to create, edit, search, and delete records for any model in your application.

Key design principles include:

• Staying close to standard Rails patterns.
• Supporting simple use cases while allowing overrides via standard Rails controllers and views.
• Using a modular architecture composed of core components and plugins.

To display a subset of a has_many relationship in the Administrate dashboard, define a new association in your ActiveRecord model using a scope (a proc or lambda) as the second argument. Because ActiveRecord infers the class name from the association name, you must explicitly provide the class_name option to point to the correct model.

class Customer < ApplicationRecord
   has_many :orders
   has_many :processed_orders, ->{ where(processed: true) }, class_name: "Order"
end

After installation, you must define routes within an admin namespace in config/routes.rb. You should also define a root route within that namespace to specify which dashboard index is shown when visiting /admin.

Rails.application.routes.draw do
  namespace :admin do
    # Add dashboard for your models here
    resources :customers
    resources :orders

    root to: "customers#index" # <--- Root route
  end
 end

If you want to organize your field views into a specific "look" directory structure (e.g., for different visual themes), use the --look flag with the generator:

rails generate administrate:field <field_name> --look <look_name>

This generates views under app/views/fields/<field_name>/looks/<look_name>/ instead of the default flat structure.

rails generate administrate:field gravatar --look custom

To disable specific Administrate actions globally, use standard Rails routing constraints in config/routes.rb to limit the available RESTful actions for a resource.

Rails.application.routes.draw do
  namespace :admin do
    # Payments can only be listed or displayed
    resources :payments, only: [:index, :show]
  end
end

By default, Administrate uses the Admin namespace. You can change this (e.g., to Supervisor) during the initial installation by providing the --namespace flag. This will change the generated controller namespaces and the routing structure.

rails generate administrate:install --namespace=supervisor

Administrate is a Ruby gem for Rails applications (version 6.0 or greater) and supports Ruby 3.0 and up.

To install, add the gem to your Gemfile, run bundle install, and then execute the installer command. The installer creates an Admin::ApplicationController and generates a Dashboard and a Controller for each of your existing ActiveRecord resources.

# Gemfile
gem "administrate"

$ rails generate administrate:install

Administrate does not include a default authentication system. You must implement your own authentication logic within your Admin::ApplicationController. The recommended pattern is to use a before_action to intercept requests and verify the user's identity.

class Admin::ApplicationController < Administrate::ApplicationController
  before_action :authenticate_admin

  def authenticate_admin
    # Implement your authentication logic here
  end
end

To use your new custom field, add it to the ATTRIBUTE_TYPES hash within your dashboard class. Map the desired attribute to your custom field class.

class UserDashboard < Administrate::BaseDashboard
  ATTRIBUTE_TYPES = {
    created_at: Field::DateTime,
    updated_at: Field::DateTime,
    name: Field::String,
    email: GravatarField,    # Use your custom field class here
    # ...
  }
end

Administrate uses Administrate::Order to control the display order of index pages and HasMany fields.

By default, the order is set to nil, which applies the model's default sort order. When a user toggles sorting by clicking a table header attribute, Administrate applies a tiebreaker using the table's primary key to ensure stable sorting (preventing records with the same attribute value from jumping positions randomly).

Note: If the table has no primary key (e.g., a join table), the tiebreaker is not used.

An alternative to adding middleware manually is to set config.api_only = false in config/application.rb. This ensures that flashes, sessions, and cookies are available globally when the application boots.

# config/application.rb
config.api_only = false