administrate_me

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 administrateme 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

Some sample images

Products list:

Products form:

Products show:

Price list:

Price form:

Price show:

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