Skip to content

Latest commit

 

History

History
326 lines (219 loc) · 10.2 KB

README.rdoc

File metadata and controls

326 lines (219 loc) · 10.2 KB
Raw

Resource Controller ↑

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.

Get It ↑

Add it as a gem dependency

config.gem 'resource_controller'

…or for the development version

config.gem 'giraffesoft-resource_controller', :lib => 'resource_controller', :source => 'http://gems.github.com'

Or install it as a gem manually

sudo gem install resource_controller

…or for the development version

sudo gem install giraffesoft-resource_controller

Or grab the source

git clone git://github.com/giraffesoft/resource_controller.git

Usage ↑

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.

Action Lifecycle ↑

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.

Before and After ↑

class ProjectsController < ResourceController::Base

  new_action.before do
    3.times { object.tasks.build }
  end

  create.after do
    object.creator = current_user
  end

end

Flash ↑

class ProjectsController < ResourceController::Base
  create.flash "Can you believe how easy it is to use resource_controller?  Neither could I!"
end

respond_to ↑

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

Scoping ↑

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

Singleton Resource ↑

If you want to create a singleton RESTful controller inherit from ResourceController::Singleton.

class AccountsController < ResourceController::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

Helpers (ResourceController::Helpers) ↑

Loading objects ↑

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

Building objects ↑

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 Resources ↑

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.

Namespaced Resources ↑

…are handled automatically, and any namespaces are always available, symbolized, in array form @ ResourceController::Helpers#namespaces

Polymorphic Resources ↑

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.

Parent Helpers ↑

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

Non-standard resource names ↑

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

Url Helpers ↑

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.

Credits ↑

resource_controller was created, and is maintained by James Golick.

License ↑

resource_controller is available under the MIT License