Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Rails RESTful controller abstraction plugin.
Ruby

This branch is 2 commits ahead, 2 commits behind jamesgolick:master

Fetching latest commit…

Cannot retrieve the latest commit at this time

Failed to load latest commit information.
generators/scaffold_resource
lib
rails
test
.gitignore
LICENSE
README.rdoc
Rakefile
TODO
VERSION.yml
init.rb
install.rb
resource_controller.gemspec
uninstall.rb

README.rdoc

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

Install it as a plugin:

script/plugin install git://github.com/giraffesoft/resource_controller.git

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.

Default Action Lifecycle

vendor/plugins/resource_controller/lib/resource_controller/actions.rb:

def index
  load_collection
  before :index
  response_for :index
end

def show
  load_object
  before :show
  response_for :show
rescue ActiveRecord::RecordNotFound
  response_for :show_fails
end

def create
  build_object
  load_object
  before :create
  if object.save
    after :create
    set_flash :create
    response_for :create
  else
    after :create_fails
    set_flash :create_fails
    response_for :create_fails
  end
end

def update
  load_object
  before :update
  if object.update_attributes object_params
    after :update
    set_flash :update
    response_for :update
  else
    after :update_fails
    set_flash :update_fails
    response_for :update_fails
  end
end

def new
  build_object
  load_object
  before :new_action
  response_for :new_action
end

def edit
  load_object
  before :edit
  response_for :edit
end

def destroy
  load_object
  before :destroy
  if object.destroy
    after :destroy
    set_flash :destroy
    response_for :destroy
  else
    after :destroy_fails
    set_flash :destroy_fails
    response_for :destroy_fails
  end
end

vendor/plugins/resource_controller/lib/resource_controller/helpers/current_objects.rb

# Used internally to load the member object in to an instance variable @#{model_name} (i.e. @post)
#
def load_object
  instance_variable_set "@#{parent_type}", parent_object if parent?
  instance_variable_set "@#{object_name}", object
end

# Used to fetch the current member object in all of the singular methods that operate on an existing member.
#
# Override this method if you'd like to fetch your objects in some alternate way, like using a permalink.
#
# class PostsController < ResourceController::Base
#   private
#     def object
#       @object ||= end_of_association_chain.find_by_permalink(param)
#     end
#   end
#
def object
  @object ||= end_of_association_chain.find(param) unless param.nil?
  @object
end

vendor/plugins/resource_controller/lib/resource_controller/helpers/singleton_customizations.rb

# Used to fetch the current object in a singleton controller.
#
# By defult this method is able to fetch the current object for resources nested with the :has_one association only. (i.e. /users/1/image # => @user.image)
# In other cases you should override this method and provide your custom code to fetch a singleton resource object, like using a session hash.
#
# class AccountsController < ResourceController::Singleton
#   private
#     def object
#       @object ||= Account.find(session[:account_id])
#     end
#   end
#  
def object
  @object ||= parent? ? end_of_association_chain : nil
end

new_action

A new object is built/initialized by build_object (which can be overridden if you need something custom).

This object can be accessed via any of: object, @object, and @model_name (f.e., @address for AddressesControler)

One of these versions of build_object, depending on whether resource is singleton or not:

vendor/plugins/resource_controller/lib/resource_controller/helpers/singleton_customizations.rb

# Builds the object, but doesn't save it, during the new, and create action.
#
def build_object
  @object ||= singleton_build_object_base.send parent? ? "build_#{model_name}".to_sym : :new, object_params
end

vendor/plugins/resource_controller/lib/resource_controller/helpers/current_objects.rb

def build_object
  @object ||= end_of_association_chain.send parent? ? :build : :new, object_params
end

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

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

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

…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

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[:tag]. 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

Something went wrong with that request. Please try again.