josevalim-inherited_resources 0.1

data/lib/inherited_resources/base_helpers.rb

@@ -0,0 +1,199 @@
+module InheritedResources #:nodoc:
+  module BaseHelpers #:nodoc:
+
+    # 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
+      # for example. When you do that, don't forget to cache the result in an
+      # instance_variable:
+      #
+      #   def collection
+      #     @projects ||= end_of_association_chain.paginate(params[:page]).all
+      #   end
+      #
+      def collection
+        get_collection_ivar || set_collection_ivar(end_of_association_chain.find(:all))
+      end
+
+      # This is how the resource is loaded.
+      #
+      # You might want to overwrite this method when you are using permalink.
+      # When you do that, don't forget to cache the result in an
+      # instance_variable:
+      #
+      #   def resource
+      #     @project ||= end_of_association_chain.find_by_permalink!(params[:id])
+      #   end
+      #
+      # You also might want to add the exclamation mark at the end of the method
+      # because it will raise a 404 if nothing can be found. Otherwise it will
+      # probably render a 500 error message.
+      #
+      def resource
+        get_resource_ivar || set_resource_ivar(end_of_association_chain.find(params[:id]))
+      end
+
+      # This method is responsable for building the object on :new and :create
+      # methods. You probably won't need to change it. Again, if you overwrite
+      # don't forget to cache the result in an instance_variable.
+      #
+      def build_resource(attributes = {})
+        get_resource_ivar || set_resource_ivar(end_of_association_chain.send(method_for_build, attributes))
+      end
+
+      # This class allows you to set a instance variable to begin your
+      # association chain. For example, usually your projects belongs to users
+      # and that means that they belong to the current logged in user. So you
+      # could do this:
+      #
+      #   def begin_of_association_chain
+      #     @current_user
+      #   end
+      #
+      # So every time we instantiate a project, we will do:
+      #
+      #   @current_user.projects.build(params[:project])
+      #   @current_user.projects.find(params[:id])
+      #
+      # The variable set in begin_of_association_chain is not sent when building
+      # urls, so this is never going to happen:
+      #
+      #   project_url(@current_user, @project)
+      #
+      # If the user actually scopes the url, you should user belongs_to method
+      # and declare that projects belong to user.
+      #
+      def begin_of_association_chain
+        nil
+      end
+
+    # Private helpers, you probably don't have to worry with them.
+    private
+
+      # Fast accessor to resource_collection_name
+      #
+      def resource_collection_name
+        resources_configuration[:self][:collection_name]
+      end
+
+      # Fast accessor to resource_instance_name
+      #
+      def resource_instance_name
+        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.
+      #
+      def parent?
+        !begin_of_association_chain.nil?
+      end
+
+      # This methods gets your begin_of_association_chain and returns the
+      # scoped association.
+      #
+      def end_of_association_chain
+        if parent?
+          begin_of_association_chain.send(resource_collection_name)
+        else
+          resource_class
+        end
+      end
+
+      # Returns the appropriated method to build the resource.
+      #
+      def method_for_build
+        parent? ? :build : :new
+      end
+
+      # Get resource ivar based on the current resource controller.
+      #
+      def get_resource_ivar
+        instance_variable_get("@#{resource_instance_name}")
+      end
+
+      # Set resource ivar based on the current resource controller.
+      #
+      def set_resource_ivar(resource)
+        instance_variable_set("@#{resource_instance_name}", resource)
+      end
+
+      # Get collection ivar based on the current resource controller.
+      #
+      def get_collection_ivar
+        instance_variable_get("@#{resource_collection_name}")
+      end
+
+      # Set collection ivar based on the current resource controller.
+      #
+      def set_collection_ivar(collection)
+        instance_variable_set("@#{resource_collection_name}", collection)
+      end
+
+      # Helper to set flash messages. It's powered by I18n API.
+      # It checks for messages in the following order:
+      #
+      #   flash.controller_name.action_name.status
+      #   flash.actions.action_name.status
+      #
+      # If none is available, a default message is set. So, if you have
+      # a CarsController, create action, it will check for:
+      #
+      #   flash.cars.create.status
+      #   flash.actions.create.status
+      #
+      # The statuses can be :notice (when the object can be created, updated
+      # or destroyed with success) or :error (when the objecy cannot be created
+      # or updated).
+      #
+      # Those messages are interpolated by using the resource class human name.
+      # This means you can set:
+      #
+      #   flash:
+      #     actions:
+      #       create:
+      #         notice: "Hooray! {{resource}} was successfully created!"
+      #
+      # But sometimes, flash messages are not that simple. Going back
+      # to cars example, you might want to say the brand of the car when it's
+      # updated. Well, that's easy also:
+      #
+      #   flash:
+      #     cars:
+      #       update:
+      #         notice: "Hooray! You just tuned your {{car_brand}}!"
+      #
+      # Since :car_name is not available for interpolation by default, you have
+      # to overwrite interpolation_options.
+      #
+      #   def interpolation_options
+      #     { :car_brand => @car.brand }
+      #   end
+      #
+      # Then you will finally have:
+      #
+      #   'Hooray! You just tuned your Aston Martin!'
+      #
+      def set_flash_message!(status, default_message = '')
+        options = {
+          :default  => [ :"flash.actions.#{action_name}.#{status}", default_message ],
+          :resource => resource_class.human_name
+        }.merge(interpolation_options)
+      
+        message = I18n.t "flash.#{controller_name}.#{action_name}.#{status}", options
+
+        flash[status] = message unless message.blank?
+      end
+
+      # Overwrite this method to provide other interpolation options when
+      # the flash message is going to be set. Check set_flash_message! for
+      # more information.
+      #
+      def interpolation_options
+        { }
+      end
+
+  end
+end

data/lib/inherited_resources/belongs_to.rb

@@ -0,0 +1,227 @@
+# = 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_instance #=> @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.
+#
+# = 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 Comment < InheritedResources::Base
+#     belongs_to :project {
+#       belongs_to :file, :message, :task, :polymorphic => true
+#     }
+#   end
+#
+# Or:
+#
+#   class Comment < 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
+#
+# If you have singleton resources, in other words, if your controller resource
+# associates to another through a has_one association, you can pass the option
+# :singleton to it. It will deal with all the details and automacally remove
+# the :index action.
+#
+#   class ManagersController < InheritedResources::Base
+#     belongs_to :project, :singleton => true # a project has one manager
+#   end
+#
+module InheritedResources #:nodoc:
+  module BelongsTo #:nodoc:
+
+    protected
+      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)
+
+        acts_as_singleton!   if singleton   = options.delete(:singleton)
+        acts_as_polymorphic! if polymorphic = options.delete(:polymorphic)
+
+        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?
+
+        # Add BelongsToHelpers if we haven't yet.
+        include BelongsToHelpers if self.parents_symbols.empty?
+
+        # Set configuration default values
+        symbols.each do |symbol|
+          symbol = symbol.to_sym
+
+          if polymorphic
+            self.parents_symbols     << :polymorphic unless self.parents_symbols.include? :polymorphic
+            self.polymorphic_symbols << symbol
+          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
+          config[:polymorphic]     = polymorphic
+        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
+
+  end
+end
+

data/lib/inherited_resources/belongs_to_helpers.rb

@@ -0,0 +1,89 @@
+module InheritedResources #:nodoc:
+  module BelongsToHelpers #: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
+
+      # Evaluate the parent given. This is used to nest parents in the
+      # association chain.
+      #
+      def evaluate_parent(parent_config, chain = nil)
+        scoped_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
+        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 chain
+      end
+
+      # 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
+      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.
+      #
+      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
+
+      end
+
+  end
+end