Rails AutoAdmin Plugin

How do I?

• Use this in Rails 1.2.1+?
  • Change the plugin name from auto-admin to auto_admin - and you'll stop getting the nil.empty? error. (Just tested this on Rails 1.2.3 and it still works)
• Contact the author?
  • rails-autoadmin@googlegroups.com / http://groups.google.com/group/rails-autoadmin
  • matthew@trebex.net
• Get patches accepted?
  • Submit them to trac... if I don't deal with them, harass me via email :)
• Change the authentication system for auto-admin? (putting user objects in the session is bad)
  • Redefine AutoAdminHelper#has_user?, AutoAdminHelper#user, AutoAdminController#login, and possibly AutoAdminController#permit_user_to_access_admin. If you need to do something other than session[:user] = nil, you'll need to redefine AutoAdminController#logout too. Patches to clean this up (especially one that moves all the authentication stuff into an optionally-included module) are very welcome. :)

What is it?

A plugin for Ruby on Rails that automagically creates an administration interface, based on your models. It is heavily inspired by the Django administration system, and the only theme currently available is based directly on Django's admin interface, designed by Wilson Miner. It shares goals with Streamlined.

Example?

  class Customer < ActiveRecord::Base
    belongs_to :store
    has_many :payments, :order => 'payment_date DESC'

    def name; first_name + ' ' + last_name; end

    sort_by :last_name
    search_by :first_name, :last_name
    filter_by :active, :store
    default_filter :active => true
    list_columns :store, :first_name, :last_name

    admin_fieldset do |b|
      b.text_field :first_name
      b.text_field :last_name
      b.select :store
    end
    admin_child_table 'Payments', :payments do |b|
      b.static_text :payment_date
      b.static_text :amount
    end
  end

What isn't it?

Scaffolding. This is not a view generator for you to then customise. Either it provides the interface you want, or it doesn't. (With a limited, but hopefully expanding, set of exceptions.)

For everyone. This is for applications that have a public interface and a restricted-access administrative interface. Its goal is not to generate views you would otherwise have to craft manually, so much as generating views you otherwise wouldn't bother to create. Of course, a neat side-effect of using this is that your boss (or your client's IT manager) can make simple database-level changes that would otherwise require a developer to use either the console or direct SQL. If you're trying to create an interface for all your users, this probably isn't for you.

Where is it?

The plugin itself is in SVN at http://svn.trebex.net/auto-admin/trunk/auto-admin. To run the tests, you need the test harness from http://svn.trebex.net/auto-admin/trunk/test-harness.

Is it usable?

Perhaps, but probably not quite yet. It currently doesn't like editable sublists, for one, and it lacks a reliable set of tests... I've TDDed a few features, but the tests covering the rest of the functionality are rather sparse.

I'm releasing mostly for selfish reasons: I'm hoping that publishing the code will shame me into fixing the nasty bits. :)

More information!

This page contains the first few sections from the README; the rest of that file comprises most of the currently existing documentation, including:

• What does it assume?
• How do I use it?
• How does it work? - Part I, Declarative UI definition
• How does it work? - Part II, Themes
• What's planned, but missing?
• Longer-term architectural considerations?

That content will be moved into this Wiki and the source code (as rdoc comments) as I get a chance.

Additional example (added by TvE)

Here is an example which demonstrates a has_many and a belongs_to relationship. I have an app with galleries of quilt photos. So I have a model for a gallery, one for a quilt, one for a photo, and one for associating a photo with a gallery (a gallery has many photos and a photo may appear in many galleries). Here is what I ended up with for the photo model:

class Photo < ActiveRecord::Base
  has_many :photo_instances
  belongs_to :quilt

  # We will have a column listing the galleries this photo
  # appears in (sort of a through relationship notion), since
  # the actual relationship is to photo_instances we need to
  # give the column a better name, i.e. "Galleries"
  column_labels(:photo_instances => "Galleries")

  # By default the relationships do not appear. Make them appear
  # in the list view and code things so we end up with a human-readable
  # value
  list_columns do |b|
    b.static_text :filename
    b.static_text :width
    b.static_text :height
    b.static_text(:quilt) do |o|
      # Think of this as being invoked as if the above line were:
      # Photo.find(...).each do |o|
      # However! It also gets invoked with o=nil once (bug?)
      # In any case, we want to display the title of the quilt
      o && o.quilt ? o.quilt.title : "(none)"
    end
    b.static_text(:photo_instances) do |o|
      # Same comments as above, for display we want to turn the
      # array of photo instances into an array of gallery titles
      # and then join all that into a comma separated string
      o && o.photo_instances.collect{ |i| i.gallery.title }.join(', ')
    end
  end

  # Here is the definition of the fields we want to be able to edit, by
  # default only the non-relationship fields appear.
  admin_fieldset do |b|
    b.text_field :filename
    b.text_field :width
    b.text_field :height
    # We want to be able to select which quilt this photo is associated with
    # For this purpose, we need to pass in an array of choices, where each
    # element consists of a pair: the string to display and the value to store
    # if this entry is selected.
    # So what we do is find all Quilts and turn that array into the array of
    # [ display value, id ] pairs.
    b.select :quilt, :choices => Quilt.find(:all).map{|q| [q.title, q.id]}
  end

  # Also display the galleries this photo appear in
  admin_child_table 'Shown in', :photo_instances do |b|
    b.static_text :gallery do |o|
      # As if we had: photo.photo_instances.each do |o|
      o && o.gallery ? o.gallery.title : "(none)"
    end
    b.static_text :position
  end
  

end

In addition to the last admin_fieldset, I'd want to be able to select which Galleries this Photo appears in. Dunno yet whether auto_admin can do that... The alternative is to handle this in the PhotoInstance portion of the admin...

More information for the above example

If you alias title to to_label (or label, name, or to_s) in Gallery and Quilt in the above example, more Magic will happen -- specifically, you won't need the blocks on the static_text calls for the belongs_to relationships, nor the custom :choices option on the select. It's quite possible that static_text :galleries would automagically do what you want for static_text :photo_instances (given a has_many :galleries, :through => :photo_instances) too. If it doesn't, patches are always welcome. :)

Maintaining a :through relationship between Gallery and Photo is currently outside auto_admin's abilities. I need to fix editable sub-lists (has_many relationships) Real Soon Now, shortly followed by implementing suitable interfaces for has_and_belongs_to_many. Once they're done, I suspect has_many :through should be minimal extra effort.