extended_inherited_resources 0.1.0

data/lib/inherited_resources/legacy/responder.rb

@@ -0,0 +1,220 @@
+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) responder searches for a template at people/index.xml;
+  #
+  #   2) if the template is not available, it will invoke :to_xml in the given resource;
+  #
+  #   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, :resources, :options
+
+    ACTIONS_FOR_VERBS = {
+      :post => :new,
+      :put => :edit
+    }
+
+    def initialize(controller, resources, options={})
+      @controller = controller
+      @request = controller.request
+      @format = controller.formats.first
+      @resource = resources.is_a?(Array) ? resources.last : resources
+      @resources = resources
+      @options = options
+      @action = options.delete(:action)
+      @default_response = options.delete(:default_response)
+    end
+
+    delegate :head, :render, :redirect_to,   :to => :controller
+    delegate :get?, :post?, :put?, :delete?, :to => :request
+
+    # Undefine :to_json and :to_yaml since it's defined on Object
+    undef_method(:to_json) if method_defined?(:to_json)
+    undef_method(:to_yaml) if method_defined?(:to_yaml)
+
+    # Initializes a new responder an invoke the proper format. If the format is
+    # not defined, call to_format.
+    #
+    def self.call(*args)
+      new(*args).respond
+    end
+
+    # Main entry point for responder responsible to dispatch to the proper format.
+    #
+    def respond
+      method = :"to_#{format}"
+      respond_to?(method) ? send(method) : to_format
+    end
+
+    # HTML format does not render the resource, it always attempt to render a
+    # template.
+    #
+    def to_html
+      default_render
+    rescue ActionView::MissingTemplate => e
+      navigation_behavior(e)
+    end
+
+    # All others formats follow the procedure below. First we try to render a
+    # template, if the template is not available, we verify if the resource
+    # responds to :to_format and display it.
+    #
+    def to_format
+      default_render
+    rescue ActionView::MissingTemplate => e
+      raise unless resourceful?
+      api_behavior(e)
+    end
+
+  protected
+
+    # This is the common behavior for "navigation" requests, like :html, :iphone and so forth.
+    def navigation_behavior(error)
+      if get?
+        raise error
+      elsif has_errors? && default_action
+        render :action => default_action
+      else
+        redirect_to resource_location
+      end
+    end
+
+    # This is the common behavior for "API" requests, like :xml and :json.
+    def api_behavior(error)
+      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
+
+    # Checks whether the resource responds to the current format or not.
+    #
+    def resourceful?
+      resource.respond_to?(:"to_#{format}")
+    end
+
+    # Returns the resource location by retrieving it from the options or
+    # returning the resources array.
+    #
+    def resource_location
+      options[:location] || resources
+    end
+
+    # If a given response block was given, use it, otherwise call render on
+    # controller.
+    #
+    def default_render
+      @default_response.call
+    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={})
+      controller.send :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
+      @action ||= ACTIONS_FOR_VERBS[request.method]
+    end
+  end
+end

data/lib/inherited_resources/locales/en.yml

@@ -0,0 +1,10 @@
+en:
+  flash:
+    actions:
+      create:
+        notice: '{{resource_name}} was successfully created.'
+      update:
+        notice: '{{resource_name}} was successfully updated.'
+      destroy:
+        notice: '{{resource_name}} was successfully destroyed.'
+        alert: '{{resource_name}} could not be destroyed.'

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/responder.rb

@@ -0,0 +1,6 @@
+module InheritedResources
+  class Responder < ActionController::Responder
+    include Responders::FlashResponder
+    include Responders::HttpCacheResponder
+  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