karsthammer-inherited_resources 1.1.2

data/lib/inherited_resources/belongs_to_helpers.rb

@@ -0,0 +1,97 @@
+module InheritedResources
+
+  # = 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
+      
+      def parent
+        @parent ||= association_chain[-1]
+      end
+      
+      def parent_type
+        parent.class.name.underscore.to_sym
+      end
+
+    private
+
+      # Evaluate the parent given. This is used to nest parents in the
+      # association chain.
+      #
+      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
+
+        parent = if chain
+          chain.send(parent_config[:collection_name])
+        else
+          parent_config[:parent_class]
+        end
+
+        parent = parent.send(parent_config[:finder], params[parent_config[:param]])
+
+        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.
+      #
+      def symbols_for_association_chain #:nodoc:
+        parents_symbols
+      end
+
+  end
+end

data/lib/inherited_resources/blank_slate.rb

@@ -0,0 +1,12 @@
+module InheritedResources
+  # An object from BlankSlate simply discards all messages sent to it.
+  class BlankSlate
+    instance_methods.each do |m|
+      undef_method m unless m =~ /^(__|object_id)/
+    end
+
+    def method_missing(*args)
+      nil
+    end
+  end
+end

data/lib/inherited_resources/class_methods.rb

@@ -0,0 +1,267 @@
+module InheritedResources
+  module ClassMethods
+
+    protected
+
+      # Used to overwrite the default assumptions InheritedResources do. Whenever
+      # this method is called, it should be on the top of your controller, since
+      # almost other methods depends on the values given to <<tt>>defaults</tt>.
+      #
+      # == Options
+      #
+      # * <tt>:resource_class</tt> - The resource class which by default is guessed
+      #                              by the controller name. Defaults to Project in
+      #                              ProjectsController.
+      #
+      # * <tt>:collection_name</tt> - The name of the collection instance variable which
+      #                               is set on the index action. Defaults to :projects in
+      #                               ProjectsController.
+      #
+      # * <tt>:instance_name</tt> - The name of the singular instance variable which
+      #                             is set on all actions besides index action. Defaults to
+      #                             :project in ProjectsController.
+      #
+      # * <tt>:route_collection_name</tt> - The name of the collection route. Defaults to :collection_name.
+      #
+      # * <tt>:route_instance_name</tt> - The name of the singular route. Defaults to :instance_name.
+      #
+      # * <tt>:route_prefix</tt> - The route prefix which is automically set in namespaced
+      #                            controllers. Default to :admin on Admin::ProjectsController.
+      #
+      # * <tt>:singleton</tt> - Tells if this controller is singleton or not.
+      #
+      def defaults(options)
+        raise ArgumentError, 'Class method :defaults expects a hash of options.' unless options.is_a? Hash
+
+        options.symbolize_keys!
+        options.assert_valid_keys(:resource_class, :collection_name, :instance_name,
+                                  :class_name, :route_prefix, :route_collection_name,
+                                  :route_instance_name, :singleton)
+
+        self.resource_class = options.delete(:resource_class)         if options.key?(:resource_class)
+        self.resource_class = options.delete(:class_name).constantize if options.key?(:class_name)
+
+        acts_as_singleton! if options.delete(:singleton)
+
+        config = self.resources_configuration[:self]
+        config[:route_prefix] = options.delete(:route_prefix) if options.key?(:route_prefix)
+
+        options.each do |key, value|
+          config[key] = value.to_sym
+        end
+
+        create_resources_url_helpers!
+      end
+
+      # Defines wich actions to keep from the inherited controller.
+      # Syntax is borrowed from resource_controller.
+      #
+      #   actions :index, :show, :edit
+      #   actions :all, :except => :index
+      #
+      def actions(*actions_to_keep)
+        raise ArgumentError, 'Wrong number of arguments. You have to provide which actions you want to keep.' if actions_to_keep.empty?
+
+        options = actions_to_keep.extract_options!
+        actions_to_remove = Array(options[:except])
+        actions_to_remove += ACTIONS - actions_to_keep.map { |a| a.to_sym } unless actions_to_keep.first == :all
+        actions_to_remove.map! { |a| a.to_sym }.uniq!
+        (instance_methods.map { |m| m.to_sym } & actions_to_remove).each do |action|
+          undef_method action, "#{action}!"
+        end
+      end
+
+      # Defines that this controller belongs to another resource.
+      #
+      #   belongs_to :projects
+      #
+      # == Options
+      #
+      # * <tt>:parent_class</tt> - Allows you to specify what is the parent class.
+      #
+      #     belongs_to :project, :parent_class => AdminProject
+      #
+      # * <tt>:class_name</tt> - Also allows you to specify the parent class, but you should
+      #                          give a string. Added for ActiveRecord belongs to compatibility.
+      #
+      # * <tt>:instance_name</tt> - The instance variable name. By default is the name of the association.
+      #
+      #     belongs_to :project, :instance_name => :my_project
+      #
+      # * <tt>:finder</tt> - Specifies which method should be called to instantiate the parent.
+      #
+      #     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])
+      #
+      # * <tt>:param</tt> - Allows you to specify params key to retrieve the id.
+      #                     Default is :association_id, which in this case is :project_id.
+      #
+      # * <tt>:route_name</tt> - Allows you to specify what is the route name in your url
+      #                          helper. By default is association name.
+      #
+      # * <tt>:collection_name</tt> - Tell how to retrieve the next collection. Let's
+      #                               suppose you have Tasks which belongs to Projects
+      #                               which belongs to companies. This will do somewhere
+      #                               down the road:
+      #
+      #      @company.projects
+      #
+      #   But if you want to retrieve instead:
+      #
+      #      @company.admin_projects
+      #
+      #   You supply the collection name.
+      #
+      # * <tt>:polymorphic</tt> - Tell the association is polymorphic.
+      #
+      # * <tt>:singleton</tt> - Tell it's a singleton association.
+      #
+      # * <tt>:optional</tt> - Tell the association is optional (it's a special
+      #                        type of polymorphic association)
+      #
+      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)
+        finder      = options.delete(:finder)
+
+        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 options: #{options.keys.inspect} to belongs to.' unless symbols.size == 1 || options.empty?
+
+        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) || begin
+            class_name = (options.delete(:class_name) || symbol).to_s.pluralize.classify
+            class_name.constantize
+          rescue NameError => e
+            raise unless e.message.include?(class_name)
+            nil
+          end
+
+          config[:collection_name] = options.delete(:collection_name) || symbol.to_s.pluralize.to_sym
+          config[:instance_name]   = options.delete(:instance_name) || symbol
+          config[:param]           = options.delete(:param) || :"#{symbol}_id"
+          config[:route_name]      = options.delete(:route_name) || symbol
+          config[:finder]          = finder || :find
+        end
+
+        if block_given?
+          class_eval(&block)
+        else
+          create_resources_url_helpers!
+        end
+        helper_method :parent, :parent?
+      end
+      alias :nested_belongs_to :belongs_to
+
+      # A quick method to declare polymorphic belongs to.
+      #
+      def polymorphic_belongs_to(*symbols, &block)
+        options = symbols.extract_options!
+        options.merge!(:polymorphic => true)
+        belongs_to(*symbols << options, &block)
+      end
+
+      # A quick method to declare singleton belongs to.
+      #
+      def singleton_belongs_to(*symbols, &block)
+        options = symbols.extract_options!
+        options.merge!(:singleton => true)
+        belongs_to(*symbols << options, &block)
+      end
+
+      # A quick method to declare optional belongs to.
+      #
+      def optional_belongs_to(*symbols, &block)
+        options = symbols.extract_options!
+        options.merge!(:optional => true)
+        belongs_to(*symbols << options, &block)
+      end
+
+    private
+
+      def acts_as_singleton! #:nodoc:
+        unless self.resources_configuration[:self][:singleton]
+          self.resources_configuration[:self][:singleton] = true
+          include SingletonHelpers
+          actions :all, :except => :index
+        end
+      end
+
+      def acts_as_polymorphic! #:nodoc:
+        unless self.parents_symbols.include?(:polymorphic)
+          include PolymorphicHelpers
+          helper_method :parent_type, :parent_class
+        end
+      end
+
+      # Initialize resources class accessors and set their default values.
+      #
+      def initialize_resources_class_accessors! #:nodoc:
+        # Initialize resource class
+        self.resource_class = begin
+          class_name = self.controller_name.classify
+          class_name.constantize
+        rescue NameError => e
+          raise unless e.message.include?(class_name)
+          nil
+        end
+
+        # Initialize resources configuration hash
+        self.resources_configuration ||= {}
+        config = self.resources_configuration[:self] = {}
+        config[:collection_name] = self.controller_name.to_sym
+        config[:instance_name]   = self.controller_name.singularize.to_sym
+
+        config[:route_collection_name] = config[:collection_name]
+        config[:route_instance_name]   = config[:instance_name]
+
+        # Deal with namespaced controllers
+        namespaces = self.controller_path.split('/')[0..-2]
+        config[:route_prefix] = namespaces.join('_') unless namespaces.empty?
+
+        # Initialize polymorphic, singleton, scopes and belongs_to parameters
+        self.parents_symbols ||= []
+        self.resources_configuration[:polymorphic] ||= { :symbols => [], :optional => false }
+      end
+
+      # Hook called on inheritance.
+      #
+      def inherited(base) #:nodoc:
+        super(base)
+        base.send :initialize_resources_class_accessors!
+        base.send :create_resources_url_helpers!
+      end
+
+  end
+end

data/lib/inherited_resources/dsl.rb

@@ -0,0 +1,26 @@
+module InheritedResources
+  # Allows controllers to write actions using a class method DSL.
+  #
+  #   class MyController < InheritedResources::Base
+  #     create! do |success, failure|
+  #       success.html { render :text => "It works!" }
+  #     end
+  #   end
+  #
+  module DSL
+    def self.included(base)
+      ACTIONS.each do |action|
+        base.class_eval <<-WRITTER
+          def self.#{action}!(options={}, &block)
+            define_method :__#{action}, &block
+            class_eval <<-ACTION
+              def #{action}
+                super(\#{options.inspect}, &method(:__#{action}))
+              end
+            ACTION
+          end
+        WRITTER
+      end
+    end
+  end
+end

data/lib/inherited_resources/polymorphic_helpers.rb

@@ -0,0 +1,155 @@
+module InheritedResources
+
+  # = 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.
+  #
+  module PolymorphicHelpers
+
+    protected
+
+      # Returns the parent type. A Comments class can have :task, :file, :note
+      # as parent types.
+      #
+      def parent_type
+        @parent_type
+      end
+
+      def parent_class
+        parent.class if @parent_type
+      end
+
+      # Returns the parent object. They are also available with the instance
+      # variable name: @task, @file, @note...
+      #
+      def parent
+        instance_variable_get("@#{@parent_type}") if @parent_type
+      end
+
+      # If the polymorphic association is optional, we might not have a parent.
+      #
+      def parent?
+        if resources_configuration[:polymorphic][:optional]
+          parents_symbols.size > 1 || !@parent_type.nil?
+        else
+          true
+        end
+      end
+
+    private
+
+      # 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_association_chain #:nodoc:
+        polymorphic_config = resources_configuration[:polymorphic]
+        parents_symbols.map do |symbol|
+          if symbol == :polymorphic
+            params_keys = params.keys
+
+            keys = polymorphic_config[:symbols].map do |poly|
+              params_keys.include?(resources_configuration[poly][:param].to_s) ? poly : nil
+            end.compact
+
+            if keys.empty?
+              raise ScriptError, "Could not find param for polymorphic association. The request" <<
+                                 "parameters are #{params.keys.inspect} and the polymorphic " <<
+                                 "associations are #{polymorphic_config[:symbols].inspect}." unless polymorphic_config[:optional]
+
+              nil
+            else
+              @parent_type = keys[-1].to_sym
+							@parent_types = keys.map(&:to_sym)
+            end
+          else
+            symbol
+          end
+        end.flatten.compact
+      end
+
+  end
+end
+