josevalim-inherited_resources 0.3 → 0.4

data/CHANGELOG

@@ -1,3 +1,10 @@
+# Version 0.4
+
+* Added :optional to belongs_to associations. It allows you to deal with
+  categories/1/products/2 and /products/2 with just one controller.
+
+* Cleaned up tests.
+
 # Version 0.3
 
 * Minor bump after three bug fixes.

data/README

@@ -1,6 +1,6 @@
 Inherited Resources
 License: MIT
-Version: 0.3
+Version: 0.4
 
 You can also read this README in pretty html at the GitHub project Wiki page:
 
@@ -347,6 +347,35 @@ When using polymorphic associations, you get some free helpers:
 Polymorphic controller is another great idea by James Golick and he also uses
 that on resource_controller.
 
+Optional belongs to
+-------------------
+
+Let's take another break from Projects. Let's suppose that we are now building
+a store, which sell products.
+
+On the website, we can show all products, but also products scoped to
+categories, brands, users, etc. In this case case, the association is optional,
+and we deal with it in the following way:
+
+  class ProductsController < InheritedResources::Base
+    belongs_to :category, :brand, :user, :polymorphic => true, :optional => true
+  end
+
+This will handle all those urls properly:
+
+  /products/1
+  /categories/2/products/5
+  /brands/10/products/3
+  /user/13/products/11
+
+This is treated as a special type of polymorphic associations, thus all helpers
+are available. As you expect, when no parent is found, the helpers return:
+
+   parent?         #=> false
+   parent_type     #=> nil
+   parent_class    #=> nil
+   parent          #=> nil
+
 Singletons
 ----------
 

data/lib/inherited_resources/base.rb

@@ -161,7 +161,6 @@
 # Let's require all needed files here. We are still on time to eager load
 # everything on multithreaded environments.
 require File.dirname(__FILE__) + '/base_helpers.rb'
-require File.dirname(__FILE__) + '/belongs_to.rb'
 require File.dirname(__FILE__) + '/belongs_to_helpers.rb'
 require File.dirname(__FILE__) + '/class_methods.rb'
 require File.dirname(__FILE__) + '/dumb_responder.rb'
@@ -176,12 +175,11 @@ module InheritedResources
     unloadable
 
     include InheritedResources::BaseHelpers
-    extend InheritedResources::BelongsTo
     extend InheritedResources::ClassMethods
 
     helper_method :collection_url, :collection_path, :resource_url, :resource_path,
                   :new_resource_url, :new_resource_path, :edit_resource_url, :edit_resource_path,
-                  :resource, :collection, :resource_class
+                  :resource, :collection, :resource_class, :parent?
 
     def self.inherited(base)
       base.class_eval do

data/lib/inherited_resources/belongs_to_helpers.rb

@@ -4,10 +4,6 @@ module InheritedResources #:nodoc:
     # Private helpers, you probably don't have to worry with them.
     private
 
-      # Overwrites the parent? method defined in base_helpers.rb.
-      # This one always returns true since it's added when associations
-      # are defined.
-      #
       def parent?
         true
       end
@@ -33,14 +29,13 @@ module InheritedResources #:nodoc:
       # parents chain and returns the scoped association.
       #
       def end_of_association_chain
-        return resource_class unless parent?
-
         chain = symbols_for_chain.inject(begin_of_association_chain) do |chain, symbol|
           evaluate_parent(resources_configuration[symbol], chain)
         end
 
-        chain = chain.send(method_for_association_chain) if method_for_association_chain
+        return resource_class unless chain
 
+        chain = chain.send(method_for_association_chain) if method_for_association_chain
         return chain
       end
 
@@ -58,31 +53,12 @@ module InheritedResources #:nodoc:
         singleton ? nil : resource_collection_name
       end
 
-      # Maps parents_symbols to build association chain.
-      #
-      # If the parents_symbols find :polymorphic, it goes through the
-      # params keys to see which polymorphic parent matches the given params.
+      # 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.
       #
       def symbols_for_chain
-        parents_symbols.map do |symbol|
-          if symbol == :polymorphic
-            params_keys = params.keys
-
-            key = polymorphic_symbols.find do |poly|
-              params_keys.include? resources_configuration[poly][:param].to_s
-            end
-
-            raise ScriptError, "Could not find param for polymorphic association.
-                                The request params keys are #{params.keys.inspect}
-                                and the polymorphic associations are
-                                #{polymorphic_symbols.inspect}." if key.nil?
-
-            instance_variable_set('@parent_type', key.to_sym)
-          else
-            symbol
-          end
-        end
-
+        parents_symbols
       end
 
   end

data/lib/inherited_resources/class_methods.rb

@@ -1,3 +1,186 @@
+# = belongs to
+#
+# This allows you to specify to belongs_to in your controller. You might use
+# this when you are having nested resources in your routes:
+#
+#   class TasksController < InheritedResources::Base
+#     belongs_to :project
+#   end
+#
+# This will do all magic assuming some defaults. It assumes that your URL to
+# access those tasks are:
+#
+#   /projects/:project_id/tasks
+#
+# But all defaults are configurable. The options are:
+#
+# * :parent_class => Allows you to specify what is the parent class.
+#
+#     belongs_to :project, :parent_class => AdminProject
+#
+# * :class_name => Also allows you to specify the parent class, but you should
+#   give a string. Added for ActiveRecord belongs to compatibility.
+#
+# * :instance_name => How this object will appear in your views. In this case
+#   the default is @project. Overwrite it with a symbol.
+#
+#     belongs_to :project, :instance_name => :my_project
+#
+# * :finder => Specifies which method should be called to instantiate the
+#   parent. Let's suppose you are using slugs ("this-is-project-title") in URLs
+#   so your tasks url would be: "projects/this-is-project-title/tasks". Then you
+#   should do this in your TasksController:
+#
+#     belongs_to :project, :finder => :find_by_title!
+#
+#   This will make your projects be instantiated as:
+#
+#     Project.find_by_title!(params[:project_id])
+#
+#   Instead of:
+#
+#     Project.find(params[:project_id])
+#
+# * param => Allows you to specify params key used to instantiate the parent.
+#   Default is :parent_id, which in this case is :project_id.
+#
+# * route_name => Allows you to specify what is the route name in your url
+#   helper. By default is 'project'. But if your url helper should be
+#   "admin_project_task_url" instead of "project_task_url", just do:
+#
+#     belongs_to :project, :route_name => "admin_project"
+#
+# = nested_belongs_to
+#
+# If for some reason you need to nested more than two resources, you can do:
+#
+#   class TasksController
+#     belongs_to :company, :project
+#   end
+#
+# ATTENTION! This DOES NOT mean polymorphic associations as in resource_controller.
+# Polymorphic associations are not supported yet.
+#
+# It means that companies have many projects which have many tasks. You URL
+# should be:
+#
+#   /companies/:company_id/projects/:project_id/tasks/:id
+#
+# Everything will be handled for you again. And all defaults will describe above
+# will be assumed. But if you have to change the defaults. You will have to
+# specify one association by one:
+#
+#   class TasksController
+#     belongs_to :company, :finder => :find_by_name!, :param => :company_name
+#     belongs_to :project
+#   end
+#
+# belongs_to is aliased as nested_belongs_to, so this provides a nicer syntax:
+#
+#   class TasksController
+#     nested_belongs_to :company, :finder => :find_by_name!, :param => :company_name
+#     nested_belongs_to :project
+#   end
+#
+# In this case the association chain would be:
+#
+#   Company.find_by_name!(params[:company_name]).projects.find(params[:project_id]).tasks.find(:all)
+#
+# When you are using nested resources, you have one more option to config.
+# Let's suppose that to get all projects from a company, you have to do:
+#
+#   Company.admin_projects
+#
+# Instead of:
+#
+#   Company.projects
+#
+# In this case, you can set the collection_name in belongs_to:
+#
+#   nested_belongs_to :project, :collection_name => 'admin_projects'
+#
+# = polymorphic associations
+#
+# In some cases you have a resource that belongs to two different resources
+# but not at the same time. For example, let's suppose you have File, Message
+# and Task as resources and they are all commentable.
+#
+# Polymorphic associations allows you to create just one controller that will
+# deal with each case.
+#
+#   class Comment < InheritedResources::Base
+#     belongs_to :file, :message, :task, :polymorphic => true
+#   end
+#
+# Your routes should be something like:
+#
+#   m.resources :files,    :has_many => :comments #=> /files/13/comments
+#   m.resources :tasks,    :has_many => :comments #=> /tasks/17/comments
+#   m.resources :messages, :has_many => :comments #=> /messages/11/comments
+#
+# When using polymorphic associations, you get some free helpers:
+#
+#   parent?         #=> true
+#   parent_type     #=> :task
+#   parent_class    #=> Task
+#   parent          #=> @task
+#
+# This polymorphic controllers thing is a great idea by James Golick and he
+# built it in resource_controller. Here is just a re-implementation.
+#
+# = optional polymorphic associations
+#
+# Let's take another break from ProjectsController. Let's suppose we are
+# building a store, which sell products.
+#
+# On the website, we can show all products, but also products scoped to
+# categories, brands, users. In this case case, the association is optional, and
+# we deal with it in the following way:
+#
+#   class ProductsController < InheritedResources::Base
+#     belongs_to :category, :brand, :user, :polymorphic => true, :optional => true
+#   end
+#
+# This will handle all those urls properly:
+#
+#   /products/1
+#   /categories/2/products/5
+#   /brands/10/products/3
+#   /user/13/products/11
+#
+# = nested polymorphic associations
+#
+# You can have polymorphic associations with nested resources. Let's suppose
+# that our File, Task and Message resources in the previous example belongs to
+# a project.
+#
+# This way we can have:
+#
+#   class CommentsController < InheritedResources::Base
+#     belongs_to :project {
+#       belongs_to :file, :message, :task, :polymorphic => true
+#     }
+#   end
+#
+# Or:
+#
+#   class CommentsController < InheritedResources::Base
+#     nested_belongs_to :project
+#     nested_belongs_to :file, :message, :task, :polymorphic => true
+#   end
+#
+# Choose the syntax that makes more sense to you. :)
+#
+# Finally your routes should be something like:
+#
+#   map.resources :projects do |m|
+#     m.resources :files,    :has_many => :comments #=> /projects/1/files/13/comments
+#     m.resources :tasks,    :has_many => :comments #=> /projects/1/tasks/17/comments
+#     m.resources :messages, :has_many => :comments #=> /projects/1/messages/11/comments
+#   end
+#
+# The helpers work in the same way as above.
+#
 # = singleton
 #
 # Singletons are usually used in associations which are related through has_one
@@ -33,7 +216,7 @@
 # When you have a singleton controller, the action index is removed.
 #
 module InheritedResources #:nodoc:
-  RESOURCES_CLASS_ACCESSORS = [ :resource_class, :resources_configuration, :parents_symbols, :singleton, :polymorphic_symbols ] unless self.const_defined? "RESOURCES_CLASS_ACCESSORS"
+  RESOURCES_CLASS_ACCESSORS = [ :resource_class, :resources_configuration, :parents_symbols, :singleton ] unless self.const_defined? "RESOURCES_CLASS_ACCESSORS"
 
   module ClassMethods #:nodoc:
 
@@ -94,6 +277,60 @@ module InheritedResources #:nodoc:
         end
       end
 
+      # Defines that this controller belongs to another resource.
+      #
+      #   belongs_to :projects
+      #
+      def belongs_to(*symbols, &block)
+        options = symbols.extract_options!
+
+        options.symbolize_keys!
+        options.assert_valid_keys(:class_name, :parent_class, :instance_name, :param, :finder, :route_name, :collection_name, :singleton, :polymorphic, :optional)
+
+        optional    = options.delete(:optional)
+        singleton   = options.delete(:singleton)
+        polymorphic = options.delete(:polymorphic)
+
+        # Add BelongsToHelpers if we haven't yet.
+        include BelongsToHelpers if self.parents_symbols.empty?
+
+        acts_as_singleton!   if singleton
+        acts_as_polymorphic! if polymorphic || optional
+
+        raise ArgumentError, 'You have to give me at least one association name.' if symbols.empty?
+        raise ArgumentError, 'You cannot define multiple associations with the options: #{options.keys.inspect}.' unless symbols.size == 1 || options.empty?
+
+        # Set configuration default values
+        symbols.each do |symbol|
+          symbol = symbol.to_sym
+
+          if polymorphic || optional
+            self.parents_symbols << :polymorphic unless self.parents_symbols.include? :polymorphic
+            self.resources_configuration[:polymorphic][:symbols]   << symbol
+            self.resources_configuration[:polymorphic][:optional] ||= optional
+          else
+            self.parents_symbols << symbol
+          end
+
+          config = self.resources_configuration[symbol] = {}
+          config[:parent_class]    = options.delete(:parent_class)
+          config[:parent_class]  ||= (options.delete(:class_name) || symbol).to_s.classify.constantize rescue nil
+          config[:collection_name] = (options.delete(:collection_name) || symbol.to_s.pluralize).to_sym
+          config[:instance_name]   = (options.delete(:instance_name) || symbol).to_sym
+          config[:param]           = (options.delete(:param) || "#{symbol}_id").to_sym
+          config[:finder]          = (options.delete(:finder) || :find).to_sym
+          config[:route_name]      = (options.delete(:route_name) || symbol).to_s
+        end
+
+        # Regenerate url helpers unless block is given
+        if block_given?
+          class_eval(&block)
+        else
+          InheritedResources::UrlHelpers.create_resources_url_helpers!(self)
+        end
+      end
+      alias :nested_belongs_to :belongs_to
+
     private
 
       # Defines this controller as singleton.
@@ -111,9 +348,9 @@ module InheritedResources #:nodoc:
       # Do not call this method on your own.
       #
       def acts_as_polymorphic!
-        if self.polymorphic_symbols.empty?
+        unless self.parents_symbols.include? :polymorphic
           include PolymorphicHelpers
-          helper_method :parent?, :parent_type, :parent_class, :parent
+          helper_method :parent, :parent_type, :parent_class
         end
       end
 
@@ -146,7 +383,7 @@ module InheritedResources #:nodoc:
         # Initialize polymorphic, singleton and belongs_to parameters
         base.singleton           = false
         base.parents_symbols     = []
-        base.polymorphic_symbols = []
+        base.resources_configuration[:polymorphic] = { :symbols => [], :optional => false }
 
         # Create helpers
         InheritedResources::UrlHelpers.create_resources_url_helpers!(base)

data/lib/inherited_resources/polymorphic_helpers.rb

@@ -8,11 +8,56 @@ module InheritedResources #:nodoc:
       end
 
       def parent_class
-        parent.class
+        parent.class if @parent_type
       end
 
       def parent
-        instance_variable_get("@#{@parent_type}")
+        instance_variable_get("@#{@parent_type}") if @parent_type
+      end
+
+    private
+
+      def parent?
+        if resources_configuration[:polymorphic][:optional]
+          !@parent_type.nil?
+        else
+          true
+        end
+      end
+
+      # Maps parents_symbols to build association chain.
+      #
+      # If the parents_symbols find :polymorphic, it goes through the
+      # params keys to see which polymorphic parent matches the given params.
+      #
+      # When optional is given, it does not raise errors if the polymorphic
+      # params are missing.
+      #
+      def symbols_for_chain
+        polymorphic_config = resources_configuration[:polymorphic]
+
+        parents_symbols.map do |symbol|
+          if symbol == :polymorphic
+            params_keys = params.keys
+
+            key = polymorphic_config[:symbols].find do |poly|
+              params_keys.include? resources_configuration[poly][:param].to_s
+            end
+
+            if key.nil?
+              raise ScriptError, "Could not find param for polymorphic association.
+                                  The request params keys are #{params.keys.inspect}
+                                  and the polymorphic associations are
+                                  #{polymorphic_symbols.inspect}." unless polymorphic_config[:optional]
+
+              nil
+            else
+              @parent_type = key.to_sym
+            end
+          else
+            symbol
+          end
+        end.compact
       end
 
   end