If you're using rails, and you've kept up with what's happening in the community, and in the framework, you're probably writing RESTful apps. You may have noticed, like I did, that most of your controllers follow the same basic pattern - the one that the scaffold_resource (just scaffold in edge/2.0) generator spits out.
I wanted a great way to hide that pattern, and describe the unique features of my controllers through a more domain-specific API. Since I tend to write a lot of nested, and polymorphic resources, I also wanted to DRY up all of that code, and make generating urls a lot more intuitive. Finally, I wanted all of that code to be well-tested, so that I could count on hacking it up when I needed new features, without breaking things.
So, I created it, and here it is.
resource_controller
A basic, out of the generator resource just requires inheriting from ResourceController::Base.
class PostsController < ResourceController::Base
end
API
Before/after callbacks, responses, and flash messages are managed through an extremely flexible API. I tried my best, here, to make syntax succinct when your needs are succinct, and allow API calls to be organized in an intuitive way. What I came up with was a scoping system, where calls to the various API methods can be chained, or scoped with a block.
Take the create action, for example. You might want to add a before block, to assign the author attribute of your post model to the current user.
class PostsController < ResourceController::Base
create.before do
@post.author << current_user
end
end
As your application matures, you may want to add an RJS response to your create method, for some AJAXy goodness. Easy.
class PostsController < ResourceController::Base
create.before do
@post.author << current_user
response do |wants|
wants.html
wants.js
end
end
end
Actually, there's even a shortcut for
adding responses. You can omit the response block, if you just want to add responses to what's already provided by resource_controller (just HTML) or has been added elsewhere.
class PostsController < ResourceController::Base
create do
before do
@post.author << current_user
end
wants.js
end
end
Since I commonly use the same RJS template for several actions, I've found this short-form really handy, because I can use a one-liner to add the same response to several actions.
class PostsController < ResourceController::Base
[create, update].each { |action| action.wants.js {render :template => "post.rjs"} }
end
Oh yeah, and you can change the flash too.
class PostsController < ResourceController::Base
create.flash "Wow! RESTful controllers are so easy with resource_controller!"
end
For more API details, and examples, see the
RDocs.
Helpers
Helpers are used internally to manage objects, generate urls, and manage parent resource associations.
If you want to customize certain controller behaviour, like member-object, and collection fetching, overriding helper methods is all it takes.
Note:For certain resource_controller functionality to work properly, user-defined helpers must make use of the other r_c helpers. The following examples do not follow that convention for clarity purposes - see the docs for more details.
If you wanted, for example, to use a permalink for your post, you'd need to alter the way that posts are fetched. Just override the object method.
class PostsController < ResourceController::Base
private
def object
@object ||= Post.find_by_permalink(param[:id])
end
end
You'll probably also want to add pagination to your index method. In the same way we altered member object fetching, we can change collection fetching behavior.
class PostsController < ResourceController::Base
private
def collection
@collection ||= Post.find(:all, :page => {:size => 10, :current => params[:page]})
end
end
Details and examples in the
RDocs.
Namespaced Resources
...are handled automatically, and any namespaces are available, symbolized, in array form from the namespaces helper method.
Nested Resources
Again, handled automatically. This can be a real pain, and it's a
lot easier with r_c. With an ActiveRecord-like syntax, just say belongs_to :model, and resource_controller takes care of the associations for you.
class CommentsController < ResourceController::Base
belongs_to :post
end
Polymorphic Resources
This is a concept that can be found in a lot of my apps. Prior to resource_controller, it was a real pain on various levels. I solved some of my problems with
urligence, and took things the rest of the way with resource_controller. It really does pretty much everything for you.
Just use the belongs_to syntax in your controller, and r_c infers whichever association (if any) is present when an action is called. The arguments passed to belongs_to are single possible parents; there is no support for deeply nested resources (although, I'm not necessarily opposed to adding it, if there is demandwe).
class CommentsController < ResourceController::Base
belongs_to :post, :product
end
In the above example, the controller will automatically infer the presence of either a parent Post, or Product, and scope all the comments to that parent. The controller will also respond without a parent if you have that in your routes.
Thanks to urligence, generating urls in your polymorphic controller's views is
really easy. The object_url, and collection_url helpers will maintain your parent resource's scope automatically.
object_url
object_url(comment)
edit_object_url
collection_url
object_url
object_url(comment)
edit_object_url
collection_url
object_url
object_url(comment)
edit_object_url
collection_url
More in the
RDocs.
Getting it
resource_controller is available under the MIT License.
It is currently available in two streams:
1.2.3+ Compatible
Install it:
svn export http://svn.jamesgolick.com/resource_controller/tags/stable vendor/plugins/resource_controller
SVN (stable): http://svn.jamesgolick.com/resource_controller/tags/stable
SVN (ongoing): http://svn.jamesgolick.com/resource_controller/trunk
Note: If you want to run the tests, cd in to the test directory, and type rake test.
Edge/Rails 2.0 Compatible
Install it:
svn export http://svn.jamesgolick.com/resource_controller/tags/edge_compatible/stable vendor/plugins/resource_controller
SVN (stable): http://svn.jamesgolick.com/resource_controller/tags/edge_compatible/stable
SVN (ongoing): http://svn.jamesgolick.com/resource_controller/branches/edge_compatible
Note: If you want to run the tests in the edge-compatible version, cd in to the test directory, and type rake rails:freeze:edge. I didn't want people to have to download all of edge rails just to get the plugin.
Also, check out the rdoc
Feedback
Drop me a line and let me know what you think. I'd love to hear your suggestions for API or implementation improvements, or anything else!
Last night at 