Rails Admin
See how to implement the popular Rails Admin gem to give applications the ability to automatically have a robust backend management dashboard along with examples on how to customize the interface.
Guide Tasks
  • Read Tutorial

What Rails Admin Provides

A common feature to add to Rails applications is a backend admin management dashboard. The Rails Admin gem has an impressive feature set and, for basic applications, provides an interface where users can:

  • Easily query the database

  • Implement custom filters for running advanced queries

  • Export records to Excel/CSV

  • Add new records from the dashboard

  • Edit/Delete records

  • Can work with both ActiveRecord or Mongoid for database ORMs

All in all Rails Admin is a powerful gem with a rich feature set, however it has a few issues that I'll discuss in the next section.

Drawbacks

I have a love/hate relationship with the Rails Admin gem. On the one hand it ships with an incredibly robust feature set and the end users are amazed at how quickly they have access to its advanced functionality. However, as soon as the custom feature requests start to come in I've found myself (on more than one occasion) eventually having to remove it completely and building a dashboard from scratch.

And that is not simply an issue with Rails Admin, for larger applications I typically prefer to build the admin dashboard myself since I've found that clients tend to eventually ask for features that take longer to implement into the respective admin gem compared with simply building the dashboard manually.

Because Rails Admin is so powerful, it makes it more difficult to work with when it comes to large customization, however that shouldn't detract from the fact that it's a great gem and is a good fit for many applications.

Also, please note that Rails Admin uses the Kaminari gem for pagination, so if you integrate this gem into an application that uses the will_paginate gem you'll need to add some initializer files to resolve dependency conflicts. I've supplied the fix during the will_paginate tutorial if you need it.

Implementation / Rails Admin Example

To get started, I'm creating a fresh Rails application, however you can follow the same steps for adding it to a pre-existing app:

rails new rails-admin-tutorial -T

After running rake db:create && rake db:migrate we're ready to install the gem. Add the following code to the Gemfile:

gem 'rails_admin', '~> 0.8.1'

Run bundle and then run the installer:

rails g rails_admin:install

This is going to ask you for the route you want the dashboard to be, I typically give the app initial followed by admin. I do this because one of the first place hackers will test is the /admin route (but for the sake of this demo we can use the default path).

This does a couple things for us:

  • It draws a new route where the dashboard can be located

  • It installs a new initializer file config/initializers/rails_admin.rb

The initializer file is where you can add custom configuration options, we'll play around with it in a little bit.

There won't be anything on the dashboard right now since our app doesn't have any models. Let's fix that by creating a new ActiveRecord model:

rails g model Post title:string content:text author:string

After running rake db:migrate let's create some fake data that will be shown in the dashboard, open up the rails console and run:

100.times do |i|
  Post.create(title: "My amazing title #{i}", content: "#{i} - Some cool content", author: "Jon Snow #{i}")
end

Ok, that worked and now we'll have some data to work with, startup the rails server and navigate to localhost:3000/admin (or whatever path name you gave to the generator). You should see a page that looks like this:

large

If you click on the Posts link on the left hand side of the page you'll see that it renders all of the test posts that we just created. You can run test queries in the Filter field and it will execute the query and return the results. For example, I'll paste in My amazing title 99 and it returns that record. If I simply type in 9 it will return a full result set where any of the columns contained the number 9.

You can also create new records by clicking on the + Add new tab. Also notice on the new page that it gives a larger text box for the content attribute, this is because we gave it the data type of text instead of string and Rails Admin customizes the field type based on the data type of the column. This feature is very cool when you have an app that uses the Carrierwave gem, Rails Admin will recognize if any of your fields are marked as fields connected to an uploader and the form will show a file upload field automatically.

One of the benefits to using a dashboard such as the Rails Admin gem is that it's dynamic, let's test this out by stopping the rails server and adding a new column to the Post model:

rails g migration add_published_status_to_posts published_status:boolean

After running rake db:migrate start the rails server backup and navigate back to the new post form localhost:3000/admin/post/new, notice how the form page now automatically picked up the new attribute? It also picked up on the fact that since I used the boolean data type that the form field element should be a checkbox, pretty amazing, right?

Going back to the post page I recommend you exploring the various filtering options, the gem gives you the ability to have compound queries, export to multiple file formats, and quite a few more powerful feature.

Where Rails Admin really shines is how elegantly it integrates data relations between database tables. Let's create a new model that will belong to the Post model:

rails g model PostTag title:string post:references

After running rake db:migrate add in a has_many call in the Post model file:

# app/models/post.rb

class Post < ActiveRecord::Base
  has_many :post_tags
end

Now if you startup the rails server and open up the app you'll see the new PostTag model, if you go to create a new one you'll notice something pretty amazing... the form automatically brings in an AJAX based dropdown box where you can search for and assign the post that the tag should be associated with, this is a feature I love.

So what happens if we need to customize the fields? I'll go through some common custom changes that you can make to the interface, let's open up the initializer file (I've removed the comments for brevity sake):

# config/initializers/rails_admin.rb

RailsAdmin.config do |config|

  config.model 'Post' do
    list do
      field :title
      field :author
      field :created_at
    end

    exclude_fields :content, :updated_at

    edit do
      exclude_fields :author
    end
  end

  config.actions do
    dashboard
    index
    new
    export
    bulk_delete
    show
    edit
    delete
    show_in_app
  end
end

I made a number of changes here, let's go through them one by one:

  1. I first created a model config block for the Post model that will encapsulate all of the customizations

  2. I created a list block, by default Rails Admin shows all of the attributes for a table, if you manually declare a list block you can dictate which columns are shown, and in what order they appear

  3. I called the exclude_fields on the :content and :updated_at columns, which will make it so they don't appear anywhere (this is slightly contrived since I'm assuming you'd want to be able to edit content, but I wanted to show that you can have any attributes not show up if you want)

  4. Lastly I updated the edit method so that users can't make any changes to the author attribute. Also note that this hides it from the new action form as well.

I hope that you found this helpful, Rails Admin is a great gem, however make sure you know the full feature set that your application needs before installing it since advanced customizations can be a little cumbersome.

Code

Resources