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.
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 :)
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.
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
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 :)
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
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!
you can visit administrate_me online documentation
administrate_me put together by people at insignia
Don’t forget to read our blog