Take back control of your Controllers. Make them awesome. Make them sleek. Make them resourceful.
REST is a fine pattern for designing controllers,
but it can be pretty repetitive.
Who wants to write out the same actions and copy the same model lookup logic
all over their application?
make_resourceful handles all that for you.
It sets up all your RESTful actions and responses with next to no code.
Everything has full, sensible default functionality.
Of course, no controller only uses the defaults.
So make_resourceful can be massively customized,
while still keeping your controllers trim and readable.
make_resourceful is an under-loved plugin. The “official” release (by hcatlin) has an annoyance: it doesn’t handle shallow routes well (e.g. if a Create action is nested by a parent record, the plugin assumes that the Show action will also be nested by a parent record, which is not true if you specify :shallow routes.)
This is a fork of kosmas58’s fork, which fixes this problem and appears to improve a few other things (like i18n).
My fork fixes my two big annoyances with make_resourceful.
1. If a :show page errors out, the exception is rescued and the plain text “No item found” is printed. Seriously? Why would anyone want that behavior? Why not just let ActiveRecord::RecordNotFound do its magic (exception locally, 404 page remotely)?
2. When a create or update fails, presumably due to an invalid record, MR by default prints a Flash message that says “There was a problem!” But 9 times out of 10, that ends up being redundant with form error messages, and the combined effect of a flash message, an error block (“3 errors prevented this…”), and highlighting of the invalid fields ends up being an eyesore. So this version removes the default “There was a problem!” flash message. If you want that, you can add it via :create_fails and :update_fails yourself.
$ ruby script/plugin install http://svn.hamptoncatlin.com/make_resourceful/trunk $ mv vendor/plugins/trunk vendor/plugins/make_resourcefulSubversion
$ svn co http://svn.hamptoncatlin.com/make_resourceful/trunk make_resourcefulThe easiest way to start with make_resourceful
is to run the resource_scaffold generator.
It uses the same syntax as the Rails scaffold_resource generator:
It does, however, require Haml[http://haml.hamptoncatlin.com].
You are using Haml, right? No?
I’ll wait here while you go fall in love with it.
If you want to try make_resourceful on one of your current controllers,
just replace the mess of repetition with this:
class FooController < ApplicationController
make_resourceful do
actions :all
end
end
Those three lines will replace the entire default controller
that comes out of the scaffold_resource generator.
Yes.
What if I want to use fancy permalinks?
def current_object
@current_object ||= current_model.find_by_permalink(params[:id])
end
What about paging?
def current_objects
@current_object ||= current_model.find(:all,
:order => "created_at DESC", :page => {:current => params[:page], :size => 10 } )
end
What if I want to do something in the middle of an action?
before :show, :index do
@page_title = "Awesome!"
end
after :create_fails do
@page_title = “Not So Awesome!”
end
What about all of my awesome respond_to blocks for my XML APIs and RJS responses?
response_for :show do |format|
format.html
format.js
format.xml
end
response_for :update_fails do |format|
format.html { render :action => ‘edit’ }
format.json { render :json => false.to_json, :status => 422 }
end
Nope! make_resourceful makes them do the right thing by default.
You only need to customize them if you want to do something special.
Yes!
The make_resourceful block is where most of the action happens.
Here you specify which actions you want to auto-generate,
what code you want to run for given callbacks,
and so forth.
You also use the block to declare various bits of information about your controller.
For instance, if the controller is nested, you’d call belongs_to.
If you wanted to expose your models as some sort of text format,
you’d call publish.
Check out the documentation of Resourceful::Builder
for more information on the methods you can call here.
make_resourceful provides lots of useful methods
that can be used in your callbacks and in your views.
They range from accessing the records you’re looking up
to easily generating URLs for a record
to getting information about the action itself.
Two of the most useful methods are current_object and current_objects
(note the subtle plurality difference).
current_objects only works for index,
and returns all the records in the current model.
current_object works for all actions other than index,
and returns the record that’s currently being dealt with.
The full documentation of the helper methods
is in Resourceful::Default::Accessors and Resourceful::Default::URLs.
make_resourceful supports easy management of nested resources.
This is set up with the Resourceful::Builder#belongs_to declaration.
Pass in the name of the parent model,
belongs_to :user
and everything will be taken care of.
When index is run for GET /users/12/albums,
parent_object[link:classes/Resourceful/Accessors.html#M000024]
will get User.find(params[:user_id]),
and current_objects[link:classes/Resourceful/Default/Accessors.html#M000010]
will get parent_object.albums.
When create is run for POST /users/12/albums,
the newly created Album will automatically belong to the user
with id 12.
The normal non-scoped actions still work, too.
GET /albums/15 runs just fine.
make_resourceful knows that since there’s no params[:user_id],
you just want to deal with the album.
You can even have a single resource nested under several different resources.
Just pass multiple parent names to the Resourceful::Builder#belongs_to, like
belongs_to :user, :artist
Then /users/15/albums and /artists/7/albums will both work.
This does, however, mean that make_resourceful only supports one level of nesting.
There’s no automatic handling of /users/15/collections/437/albums.
However, this is really the best way to organize most resources anyway;
see this article[http://weblog.jamisbuck.org/2007/2/5/nesting-resources].
If you really need a deeply nested controller,
it should be easy enough to set up on your own.
Just override current_model[link:classes/Resourceful/Default/Accessors.html#M000018].
See the next section for more details.
Not only are helper methods useful to the developer to use,
they’re used internally by the actions created by make_resourceful.
Thus one of the main ways make_resourceful can be customized
is by overriding accessors.
For instance, if you want to only look up the 10 most recent records for index,
you’re override current_objects.
If you wanted to use a different model than that suggested by the name of the controller,
you’d override current_model.
When you’re overriding methods that do SQL lookups, though, be a little cautious.
By default, these methods cache their values in instance variables
so that multiple SQL queries aren’t run on multiple calls.
When overriding them, it’s wise for you to do the same.
For instance,
def current_object
@current_object ||= current_model.find_by_name(params[:name])
end
Haven’t found all the information you need in the RDoc?
Still a little confused about something?
Don’t despair, there are still more resources available!
- Nathan Weizenbaum periodically makes blog posts about new features and versions of make_resourceful. They may be a little outdated, but they should still be useful and explanatory.
- On nesting and associations: here[http://nex-3.com/posts/55-nesting-and-make_resourceful].
- An overview of make_resourceful 0.2.0 and 0.2.2: here[http://localhost:3000/posts/54-make_resourceful-0-2-0].
- On Resourceful::Builder#publish[link:classes/Resourceful/Builder.html#M000061]and Resourceful::Serialize:
here[http://nex-3.com/posts/35-make_resourceful-the-basics-of-publish] and
here[http://nex-3.com/posts/36-make_resourceful-publish-extras]. - There’s an excellent, active Google Group (link[http://groups.google.com/group/make_resourceful]) where people will be happy to answer your questions.
- Read the source code!
It’s very straightforward,
and make_resourceful is built to encourage overriding methods
and hacking the source.
Copyright 2007 Hampton Catlin, Nathan Weizenbaum, and Jeff Hardy.
Contributions by:
- Russell Norris
- Jonathan Linowes
- Cristi Balan
- Mike Ferrier
- James Golick
- Don Petersen
- Alex Ross
- Tom Stuart
- Glenn Powell
- Kosmas Schuetz