resource_controller makes RESTful controllers easier, more maintainable, and super readable. With the RESTful controller pattern hidden away, you can focus on what makes your controller special.
Install it as a plugin:
script/plugin install git:https://github.com/giraffesoft/resource_controller.git
Or grab the source
git clone git:https://github.com/giraffesoft/resource_controller.git
Creating a basic RESTful controller is as easy as…
class PostsController < ResourceController::Base end
…or if you prefer, you can use the method-call syntax. If you need to inherit from some other class, this syntax is definitely for you:
class PostsController < ApplicationController resource_controller end
Both syntaxes are identical in their behavior. Just make sure you call resource_controller before you use any other r_c functionality in your controller.
Nobody just uses the default RESTful controller, though. resource_controller provides a simple API for customizations.
It’s really easy to make changes to the lifecycle of your actions.
Note: We had to call the new accessor "new_action", since new is somewhat reserved in ruby.
class ProjectsController < ResourceController::Base new_action.before do 3.times { object.tasks.build } end create.after do object.creator = current_user end end
class ProjectsController < ResourceController::Base create.flash "Can you believe how easy it is to use resource_controller? Neither could I!" end
You can add to what’s already there…
class ProjectsController < ResourceController::Base create.wants.js { render :template => "show.rjs" } end
Or you can create a whole new block. This syntax destroys everything that’s there, and starts again…
class ProjectsController < ResourceController::Base create.response do |wants| wants.html wants.js { render :template => "show.rjs" } end end
If you have a nested resource and want to redirect to the parent after create/update and destroy you can do this in the object controller
class CommentsController < ResourceController::Base belongs_to :post create.wants.html { redirect_to smart_url(parent_url_options) } update.wants.html { redirect_to smart_url(parent_url_options) } destroy.wants.html { redirect_to smart_url(parent_url_options) } end
Because sometimes you want to make a bunch of customizations at once, most of the helpers accept blocks that make grouping calls really easy. Is it a DSL? Maybe; maybe not. But, it’s definitely awesome.
With actions that can fail, the scoping defaults to success. That means that create.flash == create.success.flash.
class ProjectsController < ResourceController::Base create do flash "Object successfully created!" wants.js { render :template => "show.rjs" } failure.wants.js { render :template => "display_errors.rjs" } end destroy do flash "You destroyed your project. Good work." failure do flash "You cannot destroy that project. Stop trying!" wants.js { render :template => "display_errors.rjs" } end end end
If you want to create a singleton RESTful controller inherit from ResourceController::Singleton.
class AccountsController < ResourceController::Singleton end
…or if need to inherit from some other class:
class AccountsController < ApplicationController resource_controller :singleton end
Note: This type of controllers handle a single resource only so the index action and all the collection helpers (collection_url, collection_path…) are not available for them.
Loading objects in singletons is similar to plural controllers with one exception. For non-nested singleton controllers you should override the object method as it defaults to nil for them.
class AccountsController < ResourceController::Singleton private def object @object ||= Account.find(session[:account_id]) end end
In other cases you can use the default logic and override it only if you use permalinks or anything special.
Singleton nesting with both :has_many and :has_one associations is provided…
map.resource :account, :has_many => :options # /account/options, account is a singleton parent map.resources :users, :has_one => :image # /users/1/image, image is a singleton child
If you have the :has_many association with a singleton parent remember to override parent_object for your :has_many controller as it returns nil by default in this case.
class OptionsController < ResourceController::Base belongs_to :account protected def parent_object Account.find(session[:account_id]) end end
You want to add something like pagination to your controller…
class PostsController < ResourceController::Base private def collection @collection ||= end_of_association_chain.find(:all, :page => {:size => 10, :current => params[:page]}) end end
Or maybe you used a permalink…
class PostsController < ResourceController::Base private def object @object ||= end_of_association_chain.find_by_permalink(param) end end
Maybe you have some alternative way of building objects…
class PostsController < ResourceController::Base private def build_object @object ||= end_of_association_chain.build_my_object_some_funky_way object_params end end
…and there are tons more helpers in the ResourceController::Helpers
Nested controllers can be a pain, especially if routing is such that you may or may not have a parent. Not so with Resource Controller.
class CommentsController < ResourceController::Base belongs_to :post end
All of the finding, and creation, and everything will be done at the scope of the post automatically.
…are handled automatically, and any namespaces are always available, symbolized, in array form @ ResourceController::Helpers#namespaces
Everything, including url generation is handled completely automatically. Take this example…
## comment.rb class Comment belongs_to :commentable, :polymorphic => true end ## comments_controller.rb class CommentsController < ResourceController::Base belongs_to :post, :product, :user end *Note:* Your model doesn't have to be polymorphic in the ActiveRecord sense. It can be associated in whichever way you want. ## routes.rb map.resources :posts, :has_many => :comments map.resources :products, :has_many => :comments map.resources :users, :has_many => :comments
All you have to do is that, and r_c will infer whichever relationship is present, and perform all the actions at the scope of the parent object.
You also get some helpers for reflecting on your parent.
parent? # => true/false is there a parent present? parent_type # => :post parent_model # => Post parent_object # => @post
resource_controller supports overrides for every non-standard configuration of resources.
The most common example is where the resource has a different name than the associated model. Simply overriding the model_name helper will get resource_controller working with your model.
map.resources :tags ... class PhotoTag < ActiveRecord::Base ... class TagsController < ResourceController::Base private def model_name 'photo_tag' end end
In the above example, the variable, and params will be set to @tag, @tags, and params. If you’d like to change that, override object_name.
def object_name 'photo_tag' end
If you’re using a non-standard controller name, but everything else is standard, overriding resource_name will propagate through all of the other helpers.
map.resources :tags, :controller => "somethings" ... class Tag < ActiveRecord::Base ... class SomethingsController < ResourceController::Base private def resource_name 'tag' end end
Finally, the route_name helper is used by Urligence to determine which url helper to call, so if you have non-standard route names, override it.
map.resources :tags, :controller => "taggings" ... class Taggings < ActiveRecord::Base ... class TaggingsController < ResourceController::Base private def route_name 'tag' end end
Thanks to Urligence, you also get some free url helpers.
No matter what your controller looks like…
[edit_|new_]object_url # is the equivalent of saying [edit_|new_]post_url(@post) [edit_|new_]object_url(some_other_object) # allows you to specify an object, but still maintain any paths or namespaces that are present collection_url # is like saying posts_url
Url helpers are especially useful when working with polymorphic controllers.
# /posts/1/comments object_url # => /posts/1/comments/#{@comment.to_param} object_url(comment) # => /posts/1/comments/#{comment.to_param} edit_object_url # => /posts/1/comments/#{@comment.to_param}/edit collection_url # => /posts/1/comments # /products/1/comments object_url # => /products/1/comments/#{@comment.to_param} object_url(comment) # => /products/1/comments/#{comment.to_param} edit_object_url # => /products/1/comments/#{@comment.to_param}/edit collection_url # => /products/1/comments # /comments object_url # => /comments/#{@comment.to_param} object_url(comment) # => /comments/#{comment.to_param} edit_object_url # => /comments/#{@comment.to_param}/edit collection_url # => /comments
Or with namespaced, nested controllers…
# /admin/products/1/options object_url # => /admin/products/1/options/#{@option.to_param} object_url(option) # => /admin/products/1/options/#{option.to_param} edit_object_url # => /admin/products/1/options/#{@option.to_param}/edit collection_url # => /admin/products/1/options
You get the idea. Everything is automagical! All parameters are inferred.
resource_controller was created, and is maintained by James Golick.
resource_controller is available under the MIT License