QuirkeyCode

Qadmin

What

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:

Why

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!

Usage

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:

http://github.com/quirkey/qadmin-demo

Generator

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'

  

  qadmin



end

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

  # …

  can_query

  # …

end

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

Macro

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.

Block:

qadmin do |q|

  q.available_actions.exclude = [:destroy]

  q.display_columns.only = [:id, :name]

end

Hash:

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:

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.

Helpers

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.

Dependencies

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

Installing

sudo gem install qadmin
        

Or directly from github:

sudo gem install quirkey-qadmin -s http://gems.github.com
        

You can also install it as a rails plugin:

./script/plugin install git://github.com/quirkey/qadmin.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:

http://github.com/quirkey/qadmin/

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.

License

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

Contact

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 workingwithrails.com or hire me to work on your next project.