emmanuel-inherited_resources 0.9.1

data/lib/inherited_resources/legacy/responder.rb

@@ -0,0 +1,181 @@
+module ActionController #:nodoc:
+  # Responder is responsible to expose a resource for different mime requests,
+  # usually depending on the HTTP verb. The responder is triggered when
+  # respond_with is called. The simplest case to study is a GET request:
+  #
+  #   class PeopleController < ApplicationController
+  #     respond_to :html, :xml, :json
+  #
+  #     def index
+  #       @people = Person.find(:all)
+  #       respond_with(@people)
+  #     end
+  #   end
+  #
+  # When a request comes, for example with format :xml, three steps happen:
+  #
+  #   1) respond_with searches for a template at people/index.xml;
+  #
+  #   2) if the template is not available, it will create a responder, passing
+  #      the controller and the resource and invoke :to_xml on it;
+  #
+  #   3) if the responder does not respond_to :to_xml, call to_format on it.
+  #
+  # === Builtin HTTP verb semantics
+  #
+  # Rails default responder holds semantics for each HTTP verb. Depending on the
+  # content type, verb and the resource status, it will behave differently.
+  #
+  # Using Rails default responder, a POST request for creating an object could
+  # be written as:
+  #
+  #   def create
+  #     @user = User.new(params[:user])
+  #     flash[:notice] = 'User was successfully created.' if @user.save
+  #     respond_with(@user)
+  #   end
+  #
+  # Which is exactly the same as:
+  #
+  #   def create
+  #     @user = User.new(params[:user])
+  #
+  #     respond_to do |format|
+  #       if @user.save
+  #         flash[:notice] = 'User was successfully created.'
+  #         format.html { redirect_to(@user) }
+  #         format.xml { render :xml => @user, :status => :created, :location => @user }
+  #       else
+  #         format.html { render :action => "new" }
+  #         format.xml { render :xml => @user.errors, :status => :unprocessable_entity }
+  #       end
+  #     end
+  #   end
+  #
+  # The same happens for PUT and DELETE requests.
+  #
+  # === Nested resources
+  #
+  # You can given nested resource as you do in form_for and polymorphic_url.
+  # Consider the project has many tasks example. The create action for
+  # TasksController would be like:
+  #
+  #   def create
+  #     @project = Project.find(params[:project_id])
+  #     @task = @project.comments.build(params[:task])
+  #     flash[:notice] = 'Task was successfully created.' if @task.save
+  #     respond_with(@project, @task)
+  #   end
+  #
+  # Giving an array of resources, you ensure that the responder will redirect to
+  # project_task_url instead of task_url.
+  #
+  # Namespaced and singleton resources requires a symbol to be given, as in
+  # polymorphic urls. If a project has one manager which has many tasks, it
+  # should be invoked as:
+  #
+  #   respond_with(@project, :manager, @task)
+  #
+  # Check polymorphic_url documentation for more examples.
+  #
+  class Responder
+    attr_reader :controller, :request, :format, :resource, :resource_location, :options
+
+    def initialize(controller, resources, options={})
+      @controller = controller
+      @request = controller.request
+      @format = controller.formats.first
+      @resource = resources.is_a?(Array) ? resources.last : resources
+      @resource_location = options[:location] || resources
+      @options = options
+    end
+
+    delegate :head, :render, :redirect_to,   :to => :controller
+    delegate :get?, :post?, :put?, :delete?, :to => :request
+
+    # Undefine :to_json since it's defined on Object
+    undef_method :to_json
+
+    # Initializes a new responder an invoke the proper format. If the format is
+    # not defined, call to_format.
+    #
+    def self.call(*args)
+      responder = new(*args)
+      method = :"to_#{responder.format}"
+      responder.respond_to?(method) ? responder.send(method) : responder.to_format
+    end
+
+    # HTML format does not render the resource, it always attempt to render a
+    # template.
+    #
+    def to_html
+      if get?
+        render
+      elsif has_errors?
+        render :action => default_action
+      else
+        redirect_to resource_location
+      end
+    end
+
+    # All others formats try to render the resource given instead. For this
+    # purpose a helper called display as a shortcut to render a resource with
+    # the current format.
+    #
+    def to_format
+      return render unless resourceful?
+
+      if get?
+        display resource
+      elsif has_errors?
+        display resource.errors, :status => :unprocessable_entity
+      elsif post?
+        display resource, :status => :created, :location => resource_location
+      else
+        head :ok
+      end
+    end
+
+  protected
+
+    # Checks whether the resource responds to the current format or not.
+    #
+    def resourceful?
+      resource.respond_to?(:"to_#{format}")
+    end
+
+    # display is just a shortcut to render a resource with the current format.
+    #
+    #   display @user, :status => :ok
+    #
+    # For xml request is equivalent to:
+    #
+    #   render :xml => @user, :status => :ok
+    #
+    # Options sent by the user are also used:
+    #
+    #   respond_with(@user, :status => :created)
+    #   display(@user, :status => :ok)
+    #
+    # Results in:
+    #
+    #   render :xml => @user, :status => :created
+    #
+    def display(resource, given_options={})
+      render given_options.merge!(options).merge!(format => resource)
+    end
+
+    # Check if the resource has errors or not.
+    #
+    def has_errors?
+      resource.respond_to?(:errors) && !resource.errors.empty?
+    end
+
+    # By default, render the :edit action for html requests with failure, unless
+    # the verb is post.
+    #
+    def default_action
+      request.post? ? :new : :edit
+    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
+
+            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" <<
+                                 "parameters are #{params.keys.inspect} and the polymorphic " <<
+                                 "associations are #{polymorphic_config[:symbols].inspect}." unless polymorphic_config[:optional]
+
+              nil
+            else
+              @parent_type = key.to_sym
+            end
+          else
+            symbol
+          end
+        end.compact
+      end
+
+  end
+end
+

data/lib/inherited_resources/singleton_helpers.rb

@@ -0,0 +1,95 @@
+module InheritedResources
+
+  # = singleton
+  #
+  # Singletons are usually used in associations which are related through has_one
+  # and belongs_to. You declare those associations like this:
+  #
+  #   class ManagersController < InheritedResources::Base
+  #     belongs_to :project, :singleton => true
+  #   end
+  #
+  # But in some cases, like an AccountsController, you have a singleton object
+  # that is not necessarily associated with another:
+  #
+  #   class AccountsController < InheritedResources::Base
+  #     defaults :singleton => true
+  #   end
+  #
+  # Besides that, you should overwrite the methods :resource and :build_resource
+  # to make it work properly:
+  #
+  #   class AccountsController < InheritedResources::Base
+  #     defaults :singleton => true
+  #
+  #     protected
+  #       def resource
+  #         @current_user.account
+  #       end
+  #
+  #       def build_resource(attributes = {})
+  #         Account.new(attributes)
+  #       end
+  #   end
+  #
+  # When you have a singleton controller, the action index is removed.
+  #
+  module SingletonHelpers
+
+    protected
+
+      # Singleton methods does not deal with collections.
+      #
+      def collection
+        nil
+      end
+
+      # Overwrites how singleton deals with resource.
+      #
+      # If you are going to overwrite it, you should notice that the
+      # end_of_association_chain here is not the same as in default belongs_to.
+      #
+      #   class TasksController < InheritedResources::Base
+      #     belongs_to :project
+      #   end
+      #
+      # In this case, the association chain would be:
+      #
+      #   Project.find(params[:project_id]).tasks
+      #
+      # So you would just have to call find(:all) at the end of association
+      # chain. And this is what happened.
+      #
+      # In singleton controllers:
+      #
+      #   class ManagersController < InheritedResources::Base
+      #     belongs_to :project, :singleton => true
+      #   end
+      #
+      # The association chain will be:
+      #
+      #   Project.find(params[:project_id])
+      #
+      # So we have to call manager on it, not find.
+      #
+      def resource
+        get_resource_ivar || set_resource_ivar(end_of_association_chain.send(resource_instance_name))
+      end
+
+    private
+
+      # Returns the appropriated method to build the resource.
+      #
+      def method_for_association_build #:nodoc:
+        :"build_#{resource_instance_name}"
+      end
+
+      # Sets the method_for_association_chain to nil. See <tt>resource</tt>
+      # above for more information.
+      #
+      def method_for_association_chain #:nodoc:
+        nil
+      end
+
+  end
+end

data/lib/inherited_resources/url_helpers.rb

@@ -0,0 +1,173 @@
+module InheritedResources
+  # = URLHelpers
+  #
+  # When you use InheritedResources it creates some UrlHelpers for you.
+  # And they handle everything for you.
+  #
+  #  # /posts/1/comments
+  #  resource_url          # => /posts/1/comments/#{@comment.to_param}
+  #  resource_url(comment) # => /posts/1/comments/#{comment.to_param}
+  #  new_resource_url      # => /posts/1/comments/new
+  #  edit_resource_url     # => /posts/1/comments/#{@comment.to_param}/edit
+  #  collection_url        # => /posts/1/comments
+  #
+  #  # /projects/1/tasks
+  #  resource_url          # => /products/1/tasks/#{@task.to_param}
+  #  resource_url(task)    # => /products/1/tasks/#{task.to_param}
+  #  new_resource_url      # => /products/1/tasks/new
+  #  edit_resource_url     # => /products/1/tasks/#{@task.to_param}/edit
+  #  collection_url        # => /products/1/tasks
+  #
+  #  # /users
+  #  resource_url          # => /users/#{@user.to_param}
+  #  resource_url(user)    # => /users/#{user.to_param}
+  #  new_resource_url      # => /users/new
+  #  edit_resource_url     # => /users/#{@user.to_param}/edit
+  #  collection_url        # => /users
+  #
+  # The nice thing is that those urls are not guessed during runtime. They are
+  # all created when you inherit.
+  #
+  module UrlHelpers
+
+    # This method hard code url helpers in the class.
+    #
+    # We are doing this because is cheaper than guessing them when our action
+    # is being processed (and even more cheaper when we are using nested
+    # resources).
+    #
+    # When we are using polymorphic associations, those helpers rely on 
+    # polymorphic_url Rails helper.
+    #
+    def create_resources_url_helpers!
+      resource_segments, resource_ivars = [], []
+      resource_config = self.resources_configuration[:self]
+
+      singleton   = self.resources_configuration[:self][:singleton]
+      polymorphic = self.parents_symbols.include?(:polymorphic)
+
+      # Add route_prefix if any.
+      unless resource_config[:route_prefix].blank?
+        if polymorphic
+          resource_ivars << resource_config[:route_prefix].to_s.inspect
+        else
+          resource_segments << resource_config[:route_prefix]
+        end
+      end
+
+      # Deal with belongs_to associations and polymorphic associations.
+      # Remember that we don't have to build the segments in polymorphic cases,
+      # because the url will be polymorphic_url.
+      #
+      self.parents_symbols.each do |symbol|
+        if symbol == :polymorphic
+          resource_ivars << :parent
+        else
+          config = self.resources_configuration[symbol]
+          resource_segments << config[:route_name]
+          resource_ivars    << :"@#{config[:instance_name]}"
+        end
+      end
+
+      collection_ivars    = resource_ivars.dup
+      collection_segments = resource_segments.dup
+
+      # This is the default route configuration, later we have to deal with
+      # exception from polymorphic and singleton cases.
+      #
+      collection_segments << resource_config[:route_collection_name]
+      resource_segments   << resource_config[:route_instance_name]
+      resource_ivars      << :"@#{resource_config[:instance_name]}"
+
+      # In singleton cases, we do not send the current element instance variable
+      # because the id is not in the URL. For example, we should call:
+      #
+      #   project_manager_url(@project)
+      #
+      # Instead of:
+      #
+      #   project_manager_url(@project, @manager)
+      #
+      # Another exception in singleton cases is that collection url does not
+      # exist. In such cases, we create the parent collection url. So in the
+      # manager case above, the collection url will be:
+      #
+      #    project_url(@project)
+      #
+      # If the singleton does not have a parent, it will default to root_url.
+      #
+      # Finally, polymorphic cases we have to give hints to the polymorphic url
+      # builder. This works by attaching new ivars as symbols or records.
+      #
+      if singleton
+        collection_segments.pop
+        resource_ivars.pop
+
+        if polymorphic
+          resource_ivars << resource_config[:instance_name].inspect
+          new_ivars       = resource_ivars
+        end
+      elsif polymorphic
+        collection_ivars << '(@_resource_class_new ||= resource_class.new)'
+      end
+
+      generate_url_and_path_helpers nil,   :collection, collection_segments, collection_ivars
+      generate_url_and_path_helpers :new,  :resource,   resource_segments,   new_ivars || collection_ivars
+      generate_url_and_path_helpers nil,   :resource,   resource_segments,   resource_ivars
+      generate_url_and_path_helpers :edit, :resource,   resource_segments,   resource_ivars
+    end
+
+    def generate_url_and_path_helpers(prefix, name, resource_segments, resource_ivars) #:nodoc:
+      ivars = resource_ivars.dup
+
+      singleton   = self.resources_configuration[:self][:singleton]
+      polymorphic = self.parents_symbols.include?(:polymorphic)
+
+      # If it's not a singleton, ivars are not empty, not a collection or
+      # not a "new" named route, we can pass a resource as argument.
+      #
+      unless singleton || ivars.empty? || name == :collection || prefix == :new
+        ivars.push "(given_args.first || #{ivars.pop})"
+      end
+
+      # In collection in polymorphic cases, allow an argument to be given as a
+      # replacemente for the parent.
+      #
+      if name == :collection && polymorphic
+        index = ivars.index(:parent)
+        ivars.insert index, "(given_args.first || parent)"
+        ivars.delete(:parent)
+      end
+
+      # When polymorphic is true, the segments must be replace by :polymorphic
+      # and ivars should be gathered into an array, which is compacted when
+      # optional.
+      #
+      if polymorphic
+        segments = :polymorphic
+        ivars    = "[#{ivars.join(', ')}]"
+        ivars   << '.compact' if self.resources_configuration[:polymorphic][:optional]
+      else
+        segments = resource_segments.empty? ? 'root' : resource_segments.join('_')
+        ivars    = ivars.join(', ')
+      end
+
+      prefix = prefix ? "#{prefix}_" : ''
+      ivars << (ivars.empty? ? 'given_options' : ', given_options')
+
+      class_eval <<-URL_HELPERS, __FILE__, __LINE__
+        protected
+          def #{prefix}#{name}_path(*given_args)
+            given_options = given_args.extract_options!
+            #{prefix}#{segments}_path(#{ivars})
+          end
+
+          def #{prefix}#{name}_url(*given_args)
+            given_options = given_args.extract_options!
+            #{prefix}#{segments}_url(#{ivars})
+          end
+      URL_HELPERS
+    end
+
+  end
+end

data/lib/inherited_resources.rb

@@ -0,0 +1,23 @@
+# respond_to is the only file that should be loaded before hand. All others
+# are loaded on demand.
+#
+unless defined?(ActionController::Responder)
+  require File.join(File.dirname(__FILE__), 'inherited_resources', 'legacy', 'responder')
+  require File.join(File.dirname(__FILE__), 'inherited_resources', 'legacy', 'respond_to')
+end
+
+module InheritedResources
+  ACTIONS = [ :index, :show, :new, :edit, :create, :update, :destroy ] unless self.const_defined?(:ACTIONS)
+end
+
+class ActionController::Base
+  # If you cannot inherit from InheritedResources::Base you can call
+  # inherit_resource in your controller to have all the required modules and
+  # funcionality included.
+  #
+  def self.inherit_resources
+    InheritedResources::Base.inherit_resources(self)
+    initialize_resources_class_accessors!
+    create_resources_url_helpers!
+  end
+end