josevalim-inherited_resources 0.6.3 → 0.7.0

data/lib/inherited_resources/base_helpers.rb

@@ -1,8 +1,11 @@
-module InheritedResources #:nodoc:
-  module BaseHelpers #:nodoc:
+module InheritedResources
+  # Base helpers for InheritedResource work. Some methods here can be overwriten
+  # and you will need to do that to customize your controllers from time to time.
+  #
+  module BaseHelpers
 
-    # Protected helpers. You might want to overwrite some of them.
     protected
+
       # This is how the collection is loaded.
       #
       # You might want to overwrite this method if you want to add pagination
@@ -69,66 +72,95 @@ module InheritedResources #:nodoc:
         nil
       end
 
-    # Private helpers, you probably don't have to worry with them.
+      # Returns if the controller has a parent. When only base helpers are loaded,
+      # it's always false and should not be overwriten.
+      #
+      def parent?
+        false
+      end
+
+      # Overwrite this method to provide other interpolation options when
+      # the flash message is going to be set.
+      #
+      # You cannot overwrite :resource_name and :default options using this
+      # method. Check <tt>set_flash_message!</tt> for more information.
+      #
+      def interpolation_options
+        { }
+      end
+
     private
 
       # Fast accessor to resource_collection_name
       #
-      def resource_collection_name
-        resources_configuration[:self][:collection_name]
+      def resource_collection_name #:nodoc:
+        self.resources_configuration[:self][:collection_name]
       end
 
       # Fast accessor to resource_instance_name
       #
-      def resource_instance_name
-        resources_configuration[:self][:instance_name]
+      def resource_instance_name #:nodoc:
+        self.resources_configuration[:self][:instance_name]
       end
 
-      # Returns if the object has a parent. This means, if it has an object
-      # set at begin_of_association_chain is not nil.
+      # This methods gets your begin_of_association_chain, join it with your
+      # parents chain and returns the scoped association.
       #
-      def parent?
-        false
-      end
+      def end_of_association_chain #:nodoc:
+        chain = symbols_for_association_chain.inject(begin_of_association_chain) do |chain, symbol|
+          evaluate_parent(symbol, resources_configuration[symbol], chain)
+        end
 
-      # This methods gets your begin_of_association_chain and returns the
-      # scoped association.
-      #
-      def end_of_association_chain
-        if begin_of_association_chain || parent?
-          begin_of_association_chain.send(resource_collection_name)
+        if chain
+          if method_for_association_chain
+            apply_scope_to(chain.send(method_for_association_chain), resource_instance_name)
+          else
+            # This only happens when we specify begin_of_association_chain in
+            # a singletion controller without parents. In this case, the chain
+            # is exactly the begin_of_association_chain which is already an
+            # instance and then not scopable.
+            chain
+          end
         else
-          resource_class
+          apply_scope_to(resource_class, resource_instance_name)
         end
       end
 
       # Returns the appropriated method to build the resource.
       #
-      def method_for_build
+      def method_for_build #:nodoc:
         (begin_of_association_chain || parent?) ? :build : :new
       end
 
+      # Returns the name of the method to be called, before returning the end
+      # of the association chain. This is overwriten by singleton cases
+      # where no method for association chain is called.
+      #
+      def method_for_association_chain #:nodoc:
+        resource_collection_name
+      end
+
       # Get resource ivar based on the current resource controller.
       #
-      def get_resource_ivar
+      def get_resource_ivar #:nodoc:
         instance_variable_get("@#{resource_instance_name}")
       end
 
       # Set resource ivar based on the current resource controller.
       #
-      def set_resource_ivar(resource)
+      def set_resource_ivar(resource) #:nodoc:
         instance_variable_set("@#{resource_instance_name}", resource)
       end
 
       # Get collection ivar based on the current resource controller.
       #
-      def get_collection_ivar
+      def get_collection_ivar #:nodoc:
         instance_variable_get("@#{resource_collection_name}")
       end
 
       # Set collection ivar based on the current resource controller.
       #
-      def set_collection_ivar(collection)
+      def set_collection_ivar(collection) #:nodoc:
         instance_variable_set("@#{resource_collection_name}", collection)
       end
 
@@ -176,11 +208,11 @@ module InheritedResources #:nodoc:
       #
       #   'Hooray! You just tuned your Aston Martin!'
       #
-      # If your controller is namespaced, for example Rare::CarsController,
+      # If your controller is namespaced, for example Admin::CarsController,
       # the messages will be checked in the following order:
       #
-      #   flash.rare.cars.create.status
-      #   flash.rare.actions.create.status
+      #   flash.admin.cars.create.status
+      #   flash.admin.actions.create.status
       #   flash.cars.create.status
       #   flash.actions.create.status
       #
@@ -208,16 +240,6 @@ module InheritedResources #:nodoc:
         flash[status] = message unless message.blank?
       end
 
-      # Overwrite this method to provide other interpolation options when
-      # the flash message is going to be set.
-      #
-      # You cannot overwrite :resource_name and :default options using this
-      # method. Check <tt>set_flash_message!</tt> for more information.
-      #
-      def interpolation_options
-        { }
-      end
-
       # Used to allow to specify success and failure within just one block:
       #
       #   def create
@@ -226,7 +248,7 @@ module InheritedResources #:nodoc:
       #     end
       #   end
       #
-      def respond_to_with_dual_blocks(success, dual_block, options={}, &block)
+      def respond_to_with_dual_blocks(success, dual_block, options={}, &block) #:nodoc:
         responder = ActionController::MimeResponds::Responder.new(self)
 
         if dual_block
@@ -248,5 +270,19 @@ module InheritedResources #:nodoc:
         respond_to(options.merge!(:responder => responder, :prioritize => :html), &block) unless performed?
       end
 
+      # Hook to apply scopes. By default returns only the target_object given.
+      # It's extend by HasScopeHelpers.
+      #
+      def apply_scope_to(target_object, target_name) #:nodoc:
+        target_object
+      end
+
+      # Symbols chain in base helpers return nothing. This is later overwriten
+      # by belongs_to and can be complex in polymorphic cases.
+      #
+      def symbols_for_association_chain #:nodoc:
+        []
+      end
+
   end
 end

data/lib/inherited_resources/belongs_to_helpers.rb

@@ -1,66 +1,88 @@
-module InheritedResources #:nodoc:
-  module BelongsToHelpers #:nodoc:
+module InheritedResources
 
-    # Private helpers, you probably don't have to worry with them.
-    private
+  # = belongs_to
+  #
+  # Let's suppose that we have some tasks that belongs to projects. To specify
+  # this assoication in your controllers, just do:
+  #
+  #    class TasksController < InheritedResources::Base
+  #      belongs_to :project
+  #    end
+  #
+  # belongs_to accepts several options to be able to configure the association.
+  # For example, if you want urls like /projects/:project_title/tasks, you
+  # can customize how InheritedResources find your projects:
+  #
+  #    class TasksController < InheritedResources::Base
+  #      belongs_to :project, :finder => :find_by_title!, :param => :project_title
+  #    end
+  #
+  # It also accepts :route_name, :parent_class and :instance_name as options.
+  # Check the lib/inherited_resources/class_methods.rb for more.
+  #
+  # = nested_belongs_to
+  #
+  # Now, our Tasks get some Comments and you need to nest even deeper. Good
+  # practices says that you should never nest more than two resources, but sometimes
+  # you have to for security reasons. So this is an example of how you can do it:
+  #
+  #    class CommentsController < InheritedResources::Base
+  #      nested_belongs_to :project, :task
+  #    end
+  #
+  # If you need to configure any of these belongs to, you can nested them using blocks:
+  #
+  #    class CommentsController < InheritedResources::Base
+  #      belongs_to :project, :finder => :find_by_title!, :param => :project_title do
+  #        belongs_to :task
+  #      end
+  #    end
+  #
+  # Warning: calling several belongs_to is the same as nesting them:
+  #
+  #    class CommentsController < InheritedResources::Base
+  #      belongs_to :project
+  #      belongs_to :task
+  #    end
+  #
+  # In other words, the code above is the same as calling nested_belongs_to.
+  #
+  module BelongsToHelpers
+
+    protected
 
+      # Parent is always true when belongs_to is called.
+      #
       def parent?
         true
       end
 
+    private
+
       # Evaluate the parent given. This is used to nest parents in the
       # association chain.
       #
-      def evaluate_parent(parent_config, chain = nil)
+      def evaluate_parent(parent_symbol, parent_config, chain = nil) #:nodoc:
         instantiated_object = instance_variable_get("@#{parent_config[:instance_name]}")
         return instantiated_object if instantiated_object
 
-        scoped_parent = if chain
+        parent = if chain
           chain.send(parent_config[:collection_name])
         else
           parent_config[:parent_class]
         end
 
-        scoped_parent = scoped_parent.send(parent_config[:finder], params[parent_config[:param]])
-
-        instance_variable_set("@#{parent_config[:instance_name]}", scoped_parent)
-      end
-
-      # Overwrites the end_of_association_chain method.
-      #
-      # This methods gets your begin_of_association_chain, join it with your
-      # parents chain and returns the scoped association.
-      #
-      def end_of_association_chain
-        chain = symbols_for_chain.inject(begin_of_association_chain) do |chain, symbol|
-          evaluate_parent(resources_configuration[symbol], chain)
-        end
-
-        return resource_class unless chain
-
-        chain = chain.send(method_for_association_chain) if method_for_association_chain
-        return chain
-      end
+        parent = apply_scope_to(parent, parent_symbol)
+        parent = parent.send(parent_config[:finder], params[parent_config[:param]])
 
-      # If current controller is singleton, returns instance name to
-      # end_of_association_chain. This means that we will have the following
-      # chain:
-      #
-      #   Project.find(params[:project_id]).manager
-      #
-      # Instead of:
-      #
-      #   Project.find(params[:project_id]).managers
-      #
-      def method_for_association_chain
-        singleton ? nil : resource_collection_name
+        instance_variable_set("@#{parent_config[:instance_name]}", parent)
       end
 
       # Maps parents_symbols to build association chain. In this case, it
       # simply return the parent_symbols, however on polymorphic belongs to,
-      # it has some customization to deal with properly.
+      # it has some customization.
       #
-      def symbols_for_chain
+      def symbols_for_association_chain #:nodoc:
         parents_symbols
       end