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 (View Table Docs)
  • Grid: A set of rows and columns each cell being a resource (View Grid Docs)
  • Blocks: A set of rows (not tabular) each row being a resource (View Blocks Docs)
  • Blog: A title and body content, similar to a blog index (View Blog Docs)

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

Multiple Index Pages

Sometime you may want more than one index page for a resource to represent different views to the user. If multiple index pages exist, Active Admin will automatically build links at the top of the default index page. Including multiple views is simple and requires creating multiple index components in your resource.

index do
  id_column
  column :image_title
  actions
end

index as: :grid do |product|
  link_to image_tag(product.image_path), admin_product_path(product)
end

The first index component will be the default index page unless you indicate otherwise by setting :default to true.

index do
  column :image_title
  actions
end

index as: :grid, default: true do |product|
  link_to image_tag(product.image_path), admin_product_path(product)
end

Custom Index

Active Admin does not limit the index page to be a table, block, blog or grid. If you’ve created your own custom index page it can be included by setting :as to the class of the index component you created.

index as: ActiveAdmin::Views::IndexAsMyIdea do
  column :image_title
  actions
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, customize filters_form.html.erb

# app/views/admin/posts/_filters_form.html.erb
<%= active_admin_filters_form_for(@search,
  title: { label: 'Title', as: :string },
) %>

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

  • :string - A drop down for selecting “Contains”, “Equals”, “Starts with”, “Ends with” and an input for a value.
  • :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.

# app/views/admin/posts/_filters_form.html.erb
<%= active_admin_filters_form_for(@search,
  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.

# app/views/admin/posts/_filters_form.html.erb
<%= active_admin_filters_form_for(@search,
  author: { as: :check_boxes, collection: proc { Author.all } }
) %>

To override options for string or numeric filter pass filters option.

# app/views/admin/posts/_filters_form.html.erb
<%= active_admin_filters_form_for(@search,
  title: { filters: [:starts_with, :ends_with] },
) %>

Also, if you don’t need the select with the options ‘contains’, ‘equals’, ‘starts_with’ or ‘ends_with’ just add the option to the filter name with an underscore.

For example:

# app/views/admin/posts/_filters_form.html.erb
<%= active_admin_filters_form_for(@search,
  name_equals: { as: :string },
# or
  name_contains: { as: :string },
) %>

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

# app/views/admin/posts/_filters_form.html.erb
<%= active_admin_filters_form_for(@search,
  author: { label: 'Something else' }
) %>

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

You can also filter on more than one attribute of a model using the Ransack search predicate syntax. If using a custom search method, you will also need to specify the field type using :as and the label.

# app/views/admin/posts/_filters_form.html.erb
<%= active_admin_filters_form_for(@search,
  first_name_or_last_name_cont: { as: :string, label: "Name" }
) %>

Filters can also be disabled for a resource, a namespace or the entire application.

To disable for a specific resource:

ActiveAdmin.configure_resource Post do |config|
  config.filters = false
end

To disable for a namespace, in the initializer:

ActiveAdmin.setup do |config|
  config.namespace :my_namespace do |my_namespace|
    my_namespace.filters = false
  end
end

Or to disable for the entire application:

ActiveAdmin.setup do |config|
  config.filters = false
end

You can also add a filter and still preserve the default filters:

preserve_default_filters!
filter :author

Or you can also remove a filter and still preserve the default filters:

preserve_default_filters!
remove_filter :id

Index Scopes

You can define custom scopes for your index page. This will add a tab bar above the index table to quickly filter your collection on pre-defined scopes. There are a number of ways to define your scopes:

config.scope :all, default: true

# assumes the model has a scope called ':active'
config.scope :active

# renames model scope ':leaves' to ':subcategories'
config.scope "Subcategories", :leaves

# Dynamic scope name
config.scope ->{ Date.today.strftime '%A' }, :published_today

# custom scope not defined on the model
config.scope("Inactive") { |scope| scope.where(active: false) }

# conditionally show a custom controller scope
config.scope "Published", if: -> { current_admin_user.can? :manage, Posts } do |posts|
  posts.published
end

Scopes can be labelled with a translation, e.g. activerecord.scopes.invoice.expired.

Scopes groups

You can assign group names to scopes to keep related scopes together and separate them from the rest.

# a scope in the default group
config.scope :all

# two scopes used to filter by status
config.scope :active, group: :status
config.scope :inactive, group: :status

# two scopes used to filter by date
config.scope :today, group: :date
config.scope :tomorrow, group: :date

Index default sort order

You can define the default sort order for index pages:

ActiveAdmin.configure_resource Post do |config|
  config.sort_order = 'name_asc'
end

Index pagination

You can set the number of records per page as default:

ActiveAdmin.setup do |config|
  config.default_per_page = 30
end

You can set the number of records per page per resources:

ActiveAdmin.configure_resource Post do |config|
  config.per_page = 10
end

Or allow users to choose themselves using dropdown with values

ActiveAdmin.configure_resource Post do |config|
  config.per_page = [10, 50, 100]
end

You can change it per request / action too:

class Admin::PostsController < ActiveAdmin::ResourceController
  before_action only: :index do
    @per_page = 100
  end
end

You can also disable pagination:

ActiveAdmin.configure_resource Post do |config|
  config.paginate = false
end

If you have a very large database, you might want to disable SELECT COUNT(*) queries caused by the pagination info at the bottom of the page:

ActiveAdmin.configure_resource Post do |config|
  config.set_page_options :index, pagination_total: false
end

You can easily remove or customize the download links you want displayed:

# Per resource:
ActiveAdmin.configure_resource Post do |config|

  config.set_page_options :index, download_links: false
  config.set_page_options :index, download_links: [:pdf]
  config.set_page_options :index, download_links: proc{ current_user.can_view_download_links? }

end

# For the entire application:
ActiveAdmin.setup do |config|

  config.download_links = false
  config.download_links = [:csv, :xml, :json, :pdf]
  config.download_links = proc { current_user.can_view_download_links? }

end

Note: you have to actually implement PDF rendering for your action, ActiveAdmin does not provide this feature. This setting just allows you to specify formats that you want to show up under the index collection.

You’ll need to use a PDF rendering library like PDFKit or WickedPDF to get the PDF generation you want.

Table of contents