Fork me on GitHub



Qadmin is a set of helpers/macros and a generator to ease the development of admin/Content Management Systems in Rails.

The default style looks something like:


Qadmin is an extraction and refinement of the generator and templates I’ve been using to build Content Management Systems for various clients over the past number of years. The components are currently pretty basic, but tried and true to provide an instantly polished and user friendly Admin resources for non-developers.

Scaffolding is a great way to quickly build Rails apps, but the default templates an behaviors are not only limited but pretty ugly and not neccisarily user friendly. Qadmin is really a layer ontop of a basic RESTful resource that provides what I see as an ideal ‘most-of-the-way’ solution for a useable and relatively nice looking admin ‘panel’.

If the style doesnt suite you or this is not the setup you really want, theres a couple of options:

  • The CSS is pretty simple, adjust it.
  • Each HTML template is overridable, DIY.
  • Just use qadmin as a model to build you’re own generator. Really! Its not that hard!


Qadmin is a couple different pieces. A generator, a controller macro, and a set of helpers.

I’ve created a really basic rails app (that does nothing) but provides and great example of using qadmin:


The generator accepts an already defined ActiveRecord model and generates a resource, a functional test suite, some required templates, a css file, and some icons.

Assuming you have an ActiveRecord model Book:

./script/generate qadmin Book

Will generate a books_controller and a books_controller_test along with other files.

Note: The test suite is written using Shoulda. Support for different testing platforms is a possibility – If you’d like to contribute, please see Contact.

The books_controller will be pretty sparse:

class BooksController < ApplicationController
layout 'admin'



By default it envokes the qadmin macro without any configuration. Details on configuration are below, under Macro.

From here, all thats need to get a fully functioning admin is to customize the app/views/books/_form.html.erb to use the correct form elements for your fields and the app/views/books/_book.html.erb to display the Book the way you want it.

Using Restful Query it’s also really easy to add sorting to your index. If restful_query is installed in your app, just add the can_query macro to your model:

class Book < ActiveRecord::Base
# …
# …

qadmin will automagically make all of your index column heads into links that are sortable by clicking.


The controller macro qadmin is highly configurable. It automatically includes the default CRUD/RESTful resource actions:

  • index
  • new
  • show
  • create
  • edit
  • update
  • destroy

Its worth noting that overriding these is as easy as just defining and new index action below the qadmin macro.

Configuration can be done in one of two ways, though a block or a hash.


qadmin do |q|
q.available_actions.exclude = [:destroy]
q.display_columns.only = [:id, :name]


qadmin :available_actions => {:exclude => [:destroy]},
:display_columns => {:only = [:id, :name]}

I would suggest using the block version if you are doing more then one options worth of configuration as it looks nicer.

The available configuration options for qadmin:

Option Name Type Behavior Example
controller_klass Class Overrides the assumed controller that qadmin is included in BooksController
model_name String qadmin assumes the name of the model from the name of the controller/resource use this to override. Book
model_instance_name String The singular instance variable name book
model_collection_name String The plural instance variable name books
model_human_name String The humanized name for display Book
available_actions OptionSet The set of actions defined for the controller exclude, only, or assign the actions
display_columns OptionSet The set of column names to be displayed on the index
column_headers OptionSet The set of human names to give the column heads in the index
multipart_forms Boolean Set to true if you want to default forms to be multipart enabled for uploads
default_scope String Use an additional named scope or set of named scopes before the call to paginate on the index

An OptionSet is a special class that acts like an Array but also has exclude and only methods that let you adjust the defaults without having to pass a fully modified array.

Unless a view template is placed in the app/views/books folder for index, new, edit, or show the default templates are loaded from the gem.


The default views use the helpers that are outlined below, but you can override with your own custom templates and still use these helpers. You can also use these helpers outside of a qadmin enabled controller.

admin_controls generates the nice little bar of links at the top and bottom of the document.

It takes either a list of :controls or a :for which has default sets for different actions:

In app/views/books/index.html.erb

<%= admin_controls :book, :for => :index %>

In app/views/books/some_other_action.html.erb

<%= admin_controls :book, :controls => [:index, :new] %>

You can also add your own custom links to the list by invoking admin_controls as a block:
In app/views/books/index.html.erb

<% admin_controls :book, :for => :index do %>
<li><%= link_to(image_tag('admin/icon_search.png') + " Search", :action => 'search') %></li>
<% end %>

admin_table generates the nice sortable table seen in the default index view.

It takes a collection and options as a hash:

<%= admin_table @books, :attributes => [:id, :name, :author] %>

:attributes takes an array of the attributes you want to display by default.


  • rubygems >= 1.3.1
  • activesupport >= 2.3.2
  • restful_query >= 0.2.0
  • mislav-will_paginate >= 2.3.7


sudo gem install qadmin

Or directly from github:

sudo gem install quirkey-qadmin -s

You can also install it as a rails plugin:

./script/plugin install git://

Github in thier infinite awesomeness also lets you download the source in multiple formats.

Bugs/Feature Requests

The full and most up to date source is at github:

You can clone or fork from there to fix or break the code.

I’m happy to take feature requests/bug reports. Just email me (contact below) or message me on github.


This code is free to use under the terms of the MIT license.


Feel free to email me at aaron at quirkey dot com.

Please check out my blog.

If you like or use this library – I don’t want donations – but you can recommend me on or hire me to work on your next project.