giraffesoft-resource_controller 0.4.9 → 0.4.10

data/README

@@ -1 +1,312 @@
-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
+
+  svn export http://svn.jamesgolick.com/resource_controller/tags/stable vendor/plugins/resource_controller
+  
+SVN (stable): {http://svn.jamesgolick.com/resource_controller/tags/stable}[http://svn.jamesgolick.com/resource_controller/tags/stable]
+
+SVN (ongoing): {http://svn.jamesgolick.com/resource_controller/trunk}[http://svn.jamesgolick.com/resource_controller/trunk]
+
+= 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
+
+== 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
+
+== 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
+
+== 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].
+
+== License
+
+resource_controller is available under the {MIT License}[http://en.wikipedia.org/wiki/MIT_License]

data/lib/resource_controller.rb

@@ -1,14 +1,19 @@
 module ResourceController
-  ACTIONS          = [:index, :show, :new_action, :create, :edit, :update, :destroy].freeze
-  FAILABLE_ACTIONS = ACTIONS - [:index, :new_action, :edit].freeze
-  NAME_ACCESSORS   = [:model_name, :route_name, :object_name]  
+  ACTIONS           = [:index, :show, :new_action, :create, :edit, :update, :destroy].freeze
+  SINGLETON_ACTIONS = (ACTIONS - [:index]).freeze
+  FAILABLE_ACTIONS  = ACTIONS - [:index, :new_action, :edit].freeze
+  NAME_ACCESSORS    = [:model_name, :route_name, :object_name]  
   
   module ActionControllerExtension
     unloadable
     
-    def resource_controller
+    def resource_controller(*args)
       include ResourceController::Controller
-    end
+      
+      if args.include?(:singleton)
+        include ResourceController::Helpers::SingletonCustomizations
+      end
+    end  
   end
 end
 

data/lib/resource_controller/class_methods.rb

@@ -10,8 +10,10 @@ module ResourceController
       config = {}
       config.merge!(opts.pop) if opts.last.is_a?(Hash)
 
+      all_actions = (singleton? ? ResourceController::SINGLETON_ACTIONS : ResourceController::ACTIONS) - [:new_action] + [:new]
+      
       actions_to_remove = []
-      actions_to_remove += (ResourceController::ACTIONS - [:new_action] + [:new]) - opts unless opts.first == :all                
+      actions_to_remove += all_actions - opts unless opts.first == :all                
       actions_to_remove += [*config[:except]] if config[:except]
       actions_to_remove.uniq!
 

data/lib/resource_controller/controller.rb

@@ -57,6 +57,12 @@ module ResourceController
             flash "Successfully removed!"
             wants.html { redirect_to collection_url }
           end
+          
+          class << self
+            def singleton?
+              false
+            end
+          end
         end
       end
   end

data/lib/resource_controller/helpers/nested.rb

@@ -1,7 +1,7 @@
 # Nested and Polymorphic Resource Helpers
 #
 module ResourceController::Helpers::Nested
-  protected
+  protected    
     # Returns the relevant association proxy of the parent. (i.e. /posts/1/comments # => @post.comments)
     #
     def parent_association
@@ -11,7 +11,19 @@ module ResourceController::Helpers::Nested
     # Returns the type of the current parent
     #
     def parent_type
-      @parent_type ||= [*belongs_to].find { |parent| !params["#{parent}_id".to_sym].nil? }
+      @parent_type ||= parent_type_from_params || parent_type_from_request
+    end
+    
+    # Returns the type of the current parent extracted from params
+    #    
+    def parent_type_from_params
+      [*belongs_to].find { |parent| !params["#{parent}_id".to_sym].nil? }
+    end
+    
+    # Returns the type of the current parent extracted form a request path
+    #    
+    def parent_type_from_request
+      [*belongs_to].find { |parent| request.path.split('/').include? parent.to_s }
     end
     
     # Returns true/false based on whether or not a parent is present.
@@ -20,6 +32,12 @@ module ResourceController::Helpers::Nested
       !parent_type.nil?
     end
     
+    # Returns true/false based on whether or not a parent is a singleton.
+    #    
+    def parent_singleton?
+      !parent_type_from_request.nil?
+    end
+    
     # Returns the current parent param, if there is a parent. (i.e. params[:post_id])
     def parent_param
       params["#{parent_type}_id".to_sym]
@@ -34,7 +52,7 @@ module ResourceController::Helpers::Nested
     # Returns the current parent object if a parent object is present.
     #
     def parent_object
-      parent? ? parent_model.find(parent_param) : nil
+      parent? && !parent_singleton? ? parent_model.find(parent_param) : nil
     end
     
     # If there is a parent, returns the relevant association proxy.  Otherwise returns model.

data/lib/resource_controller/helpers/singleton_customizations.rb

@@ -0,0 +1,60 @@
+# Singleton Resource Helpers
+# 
+# Used internally to transform a plural RESTful controller into a singleton
+#
+module ResourceController::Helpers::SingletonCustomizations
+  def self.included(subclass)
+    subclass.class_eval do  
+      methods_to_undefine = [:param, :index, :collection, :load_collection, :collection_url, 
+        :collection_path, :hash_for_collection_url, :hash_for_collection_path]
+      methods_to_undefine.each { |method| undef_method(method) if method_defined? method }
+      
+      class << self
+        def singleton?
+          true
+        end
+      end
+    end
+  end
+  
+  protected
+    # 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
+
+    # Returns the :has_one association proxy of the parent. (i.e. /users/1/image # => @user.image)
+    #  
+    def parent_association
+      @parent_association ||= parent_object.send(model_name.to_sym)
+    end
+  
+    # Used internally to provide the options to smart_url in a singleton controller.
+    #  
+    def object_url_options(action_prefix = nil, alternate_object = nil)
+      [action_prefix] + namespaces + [parent_url_options, route_name.to_sym]
+    end
+  
+    # 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
+    
+    # Singleton controllers don't build off of association proxy, so we can't use end_of_association_chain here
+    #
+    def singleton_build_object_base
+      parent? ? parent_object : model
+    end
+end