= 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

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

= Usage

Creating a basic RESTful controller is as easy as inheriting from +ResourceController::Base+

  class PostsController < ResourceController::Base
  end

...or if you prefer, you can use the method-call syntax.  Since +ResourceController::Base+ now properly
supports inheritance, the above way is the preferred way to use +resource_controller+, but this also
works:

  class PostsController < ApplicationController
    resource_controller
  end

Both syntaxes are identical in their behavior.

When loaded, +resource_controller+ will actually iterate through all the routes you have defined in +routes.rb+.
A sequence of callbacks is defined for each resource, which can then be customized. For member routes,
the default action will attempt to lookup the record in the model and render it. For collection routes,
the default action will use +find(:all)+ to retrieve all models. Assuming this set of routes:

  map.resources :users, :collection => {:extended_list => :get}, :member => {:rename => :post}

Note that +ResourceController::Base+ itself inherits from +ApplicationController+, so all of your global
filters will still be applied.

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. For each action, the following
callbacks are executed in order:

  build
  before
  action  # only on non-GET requests
  after
  flash
  wants

Each of these callbacks can be redefined by calling them on the name of the action:

  index.build { #do stuff }
  index.flash "Success"
  index.wants.html

Note: We had to call the new accessor "new_action", since new is somewhat reserved in ruby.

=== Build

Build is called on each request. For default actions created, these will either 
load an object or a collection:

  index.build { load_collection }
  edit.build  { load_object }

If you have defined a custom resource, you may have to alter these, although +resource_controller+
tries to figure it out. Using our example routes, these would be created for you:

  extended_list { load_collection }
  rename { load_object }

To change one, simply redefine the block.

  extended_list { @users = User.find(:all, :include => [:profile]) }

If you want to change the way all objects are looked up for a given controller, see
below under "Building objects".

=== Action

The +action+ callback is *only* called on non-GET requests. This provides safety against
making changes to your database via the GET request method. In addition, it provides an easy
way to implement those special actions (such as "login") that you would normally wrap in
an +if request.post?+ block.

The following are two examples of RESTful actions created for you:

  create.action  { object.save }
  destroy.action { object.destroy }

If you were building a login method, you might define an +action+ like this:

  login.action { Account.login(params[:login]) }

If this returns true, then the action is considered a success. If it returns
false, then the action is considered a failure.

=== Response (respond_to)

Since +resource_controller+ already understands whether an action was successful or not
based you the +build+ and +action+ calls, you can define two separate +respond_to+
blocks:

  login.success.wants.html  # login.rhtml
  login.failure.wants.html { render :text => "Your login failed" }

The response type defaults to success, meaning that +wants.html+ == +wants.success.html+:

  login.wants.html  # same as login.success.wants.html

When defining responses, 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

=== Flash

You can also set the flash on a callback basis. The appropriate one will automatically be used:

  class ProjectsController < ResourceController::Base
    create.flash "Can you believe how easy it is to use resource_controller?  Neither could I!"
    create.failure.flash "A major boo-boo happened. Uh-oh!"
  end

== Advanced Usage

=== Before and After

The +before+ callback is used to perform steps once your object or colletion has
been built, but before +action+ is called. Conversely, +after+ is called once
+action+ has been executed, *but only on success*

  class ProjectsController < ResourceController::Base
    
    new_action.before do
      3.times { object.tasks.build }
    end
    
    create.after do
      # This won't be called on failure
      object.creator = current_user
    end
    
  end
  
=== Scoping with Blocks

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.

  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

=== Rescuing Exceptions

+resource_controller+ also adds a handy way to catch exceptions, and count these as failures.
That way, you don't have to check for failures *and* exceptions everywhere:

  show do
    build { load_object }
    rescues ActiveRecord::RecordNotFound
    wants.html
    wants.failure.html { render :text => "Record not found" }
  end

If you use +rescues+, you can also check the +exception+ accessor to print out the exception
that occurred:

  destroy do
    action { object.destroy }
    rescues ActiveRecord::StatementInvalid
    wants.failure.html { render :text => exception || "Error occurred" }
  end

Remember that exceptions handled with +rescues+ are still counted as failures - this just
prevents your views from blowing up. If you want to ignore certain exceptions, you need
to wrap your +action+ in a begin/end block.

== 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 +resource_controller+ 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}[http://jamesgolick.com].
Dynamic route detection and callbacks added by {Nate Wiger}[http://nate.wiger.org]

== License

resource_controller is available under the {MIT License}[http://en.wikipedia.org/wiki/MIT_License]