All about administrate_me plugin

administrate_me is a Rails plugin conceived to simplify the creation of administrative backend interfases on a Rails project. This way you can have basic CRUD with a nice user interfase almost for free.

Dependencies

administrate_me master version requires rails 2.2.2 or edge rails.

If you need to run administrate_me with a previous rails version, you can use rails2 branch; this version works fine with rails 2.0.x and 2.1.×.

It will also take advange of other installed plugins on the same project, such as will_paginate and bundle_fu.

will_paginate will be used to paginate records of each table and bundle_fu to automatically bundle assets files (javascripts and stylesheets) to increase loading performace.

Important!: unfortunately administrate_me doesn’t support rails gems older than 2.0. It likes the life on the edge :)

Installation

To install administrate_me plugin into your rails project (rails version >= 2.2.2) just run:


  ruby script/plugin install git://github.com/insignia/administrate_me.git

For projects running with rails < 2.2, you’ll have to clone plugin’s git repository, checkout rails2 branch and delete .git folder after it, just like this:


  git clone git://github.com/insignia/administrate_me.git vendor/plugins/administrate_me
  cd vendor/plugins/administrate_me
  git checkout -b rails2 origin/rails2
  rm vendor/plugins/administrate_me/.git -rf

Or you can download a tarball from github, and extract the files into vendor/plugins/ folder.

Setup

Once you’ve installed the plugin, you’ll have to import plugin’s asset files into your project, in order to do that, you can run:


  rake admin:import_files

Then, administrate_me requires a little extra configuration which you can put into your application.rb:


  class ApplicationController < ActionController::Base
    helper :all # include all helpers, all the time
    protect_from_forgery # :secret => 'ed1896d8d25a5a534d1a14d0f74664f4'
    
    # This will set a products module or tab on the backend interfase
    set_module :products 
  end

also, you can provide administrate_me with an optionally set of info for beautifying your application’s backend:


  class ApplicationController < ActionController::Base
    helper :all # include all helpers, all the time
    protect_from_forgery # :secret => 'ed1896d8d25a5a534d1a14d0f74664f4'
    
    # owner and app_name methods will be published into application's backend
    def owner
      "who's the owner?"
    end
    
    def app_name
      "your app's name"
    end    
    
    # This will set a products module or tab on the backend interfase
    set_module :products 
  end

Usage (..or building a rails application with administrate_me)

Basic usage

Let’s say you need to create a little backend to manage a products database. Here’s the recipe:

Create a new rails application


  rails store
  cd store

Install administrate_me plugin


  ruby script/plugin install git://github.com/insignia/administrate_me.git

Copy plugin’s asset files into your project


  rake admin:import_files

Create a very simple product model and run the migration


  ruby script/generate model Product name:string description:text
  rake db:migrate

Create an empty controller to admin the created model


  ruby script/generate controller products

Add a new route to product resources on config/routes.rb


  map.resources :products

Create views for you controller

Automatically create controller’s views with this generator. All templates needed will be created using all the table fields, you can edit those files later to include/exclude fields on your demand.


  ruby script/generate admin_view products

Include administrate_me configuration into your controller


  class ProductsController < ApplicationController
    administrate_me do |a|
      a.search :name, :description
      a.order  :name
    end
  end

Add general configuration for the application


  class ApplicationController < ActionController::Base
    helper :all # include all helpers, all the time
    protect_from_forgery # :secret => 'ed1896d8d25a5a534d1a14d0f74664f4'
    
    # owner and app_name methods will be published into application's backend
    def owner
      "Lorem Ipsum Inc."
    end
    
    def app_name
      "Store Administration"
    end    
    
    # This will set a products module or tab on the backend interfase
    set_module :products 
  end

So, what are you waiting for!? Run the application!


   ruby script/server

Awesome!? Have fun playing aroung with your brand new backend :)

What about nested resources?

Now, let’s say you need to add a set of prices for each product.

Create a simple price model


  ruby script/generate model Price product_id:integer value:decimal
  rake db:migrate

Create another empty controller for the generated model


  ruby script/generate controller prices

Edit your routes.rb file


  map.resources :products, :has_many => :prices

Create views for this controller


  ruby script/generate admin_view prices

Setup administrate in the controller


  class PricesController < ApplicationController
    administrate_me do |a|
      a.belongs_to :product, :context => :name
      a.search :value
    end
  end

Modify your product page to link to prices


  <%# app/views/products/show.html.erb %>
  <%=
    present :elegant do |p|
      p.header do |r|
        r.field 'Name', @resource.name
      end
      p.body do |r|
        r.field 'Description', @resource.description
        r.field 'Created at', @resource.created_at
        r.field 'Updated at', @resource.updated_at
      end
      p.actions do |r|
        r.text link_to('manage prices', product_prices_path(@resource))
        r.text edit_action
        r.text destroy_action
        r.text back_action
      end
    end
  %>

Modify your product listing page to add a quick link to prices


  <%# app/views/products/_list.html.erb %>
  <%= list_builder_for @records do |list|
        list.name
        list.description
        list.html :caption => '' do |product|
          link_to('manage prices', product_prices_path(product))
        end
      end %>

Ready for rock ’n roll?

Be kind and refresh your brower, please? :D

Don’t be a bad boy and cover your code with specs!

administrate_me includes a set of rspec shared behaviours and matchers to help you to cover your controller’s code with spec.

Note: in order for this to work, you’ll have to add rspec support into your project

Tell your controllers to behave


  # this code should go into spec/controllers/products_controller_spec.rb
  require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')

  describe ProductsController do

    before(:each) do
      @mock_model_class = Product
    end

    it_should_behave_like 'basic administrate_me'

  end
  
  describe ProductsController do
    it "should be searchable by name" do
      ProductsController.should be_searchable_by(:name)
    end
    
    it "should be searchable by description" do
      ProductsController.should be_searchable_by(:description)
    end
  end

administrate_me also includes rspec support for nested controllers…


   # this code should go into spec/controllers/prices_controller_spec.rb
   require File.expand_path(File.dirname(__FILE__) + '/../../spec_helper')

   describe PricesController do
     before do
       @mock_model_class = Price
       @parent_name      = 'product'
     end

     it_should_behave_like 'basic administrate_me with parent'

   end

now you have a very solid rails application :D

Enjoy!

More info…

you can visit administrate_me online documentation

Credits

administrate_me put together by people at insignia

Don’t forget to read our blog

mlightner/administrate_me