josevalim-inherited_resources 0.6.3 → 0.7.0

data/lib/inherited_resources/class_methods.rb

@@ -1,250 +1,37 @@
-# = 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
-#   "myproject_task_url" instead of "project_task_url", just do:
-#
-#     belongs_to :project, :route_name => "myproject"
-#
-#   But if you want to use namespaced routes, you can do:
-#
-#     defaults :route_prefix => :admin
-#
-#   That would generate "admin_project_task_url".
-#
-# = 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
-# 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 InheritedResources #:nodoc:
-  RESOURCES_CLASS_ACCESSORS = [ :resource_class, :resources_configuration, :parents_symbols, :singleton ] unless self.const_defined? "RESOURCES_CLASS_ACCESSORS"
-
-  module ClassMethods #:nodoc:
+module InheritedResources
+  RESOURCES_CLASS_ACCESSORS = [ :resource_class, :resources_configuration,
+                                :parents_symbols, :scopes_configuration ] unless self.const_defined?(:RESOURCES_CLASS_ACCESSORS)
+
+  module ClassMethods
 
     protected
 
-      # When you inherit from InheritedResources::Base, we make some assumptions on
-      # what is your resource_class, instance_name and collection_name.
+      # 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>.
       #
-      # You can change those values by calling the class method <tt>defaults</tt>.
-      # This is useful, for example, in an accounts controller, where the object
-      # is an User but controller and routes are accounts.
+      # == Options
       #
-      #   class AccountController < InheritedResources::Base
-      #     defaults :resource_class => User, :instance_name => 'user',
-      #              :collection_name => 'users', :singleton => true
-      #   end
+      # * <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.
       #
-      # If you want to change your urls, you can use :route_instance_name and
-      # :route_collection_name helpers.
+      # * <tt>:route_collection_name</tt> - The name of the collection route. Defaults to :collection_name.
       #
-      # You can also provide :class_name, which is the same as :resource_class
-      # but accepts string (this is given for ActiveRecord compatibility).
+      # * <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
@@ -287,16 +74,194 @@ module InheritedResources #:nodoc:
         actions_to_remove += RESOURCES_ACTIONS.map{|a| a.to_s } - actions_to_keep unless actions_to_keep.first == 'all'
         actions_to_remove.uniq!
 
-        # Undefine actions that we don't want
         (instance_methods & actions_to_remove).each do |action|
           undef_method action, "#{action}!"
         end
       end
 
+      # Detects params from url and apply as scopes to your classes.
+      #
+      # Your model:
+      #
+      #   class Graduation < ActiveRecord::Base
+      #     named_scope :featured, :conditions => { :featured => true }
+      #     named_scope :by_degree, proc {|degree| { :conditions => { :degree => degree } } }
+      #   end
+      #
+      # Your controller:
+      #
+      #   class GraduationsController < InheritedResources::Base
+      #     has_scope :featured, :boolean => true, :only => :index
+      #     has_scope :by_degree, :only => :index
+      #   end
+      #
+      # Then for each request:
+      #
+      #   /graduations
+      #   #=> acts like a normal request
+      #
+      #   /graduations?featured=true
+      #   #=> calls the named scope and bring featured graduations
+      #
+      #   /graduations?featured=true&by_degree=phd
+      #   #=> brings featured graduations with phd degree
+      #
+      # You can also specify the target of the scope. Let's suppose that a
+      # Graduation has many students:
+      #
+      #   class StudentsController < InheritedResources::Base
+      #     belongs_to :graduation
+      #
+      #     has_scope :featured, :on => :graduation, :boolean => true, :only => :index
+      #     has_scope :by_degree, :on => :graduation, :only => :index
+      #   end
+      #
+      # You can also do this in a block:
+      #
+      #   class StudentsController < InheritedResources::Base
+      #     belongs_to :graduation do
+      #       has_scope :featured,  :boolean => true, :only => :index
+      #       has_scope :by_degree, :only => :index
+      #     end
+      #   end
+      #
+      # Or even better:
+      #
+      #   class StudentsController < InheritedResources::Base
+      #     belongs_to :graduation do
+      #       load_scopes_from GraduationsController
+      #     end
+      #   end
+      #
+      # Another feature is that you can retrive the current scopes in use with
+      # the method <tt>current_scopes</tt> that returns a hash.
+      #
+      # == Options
+      #
+      # * <tt>:on</tt> - In each resource the scope is applied to. Defaults to the resource class.
+      #
+      # * <tt>:boolean</tt> - When set to true, call the scope only when the params is true or 1,
+      #                       and does not send the value as argument.
+      #
+      # * <tt>:only</tt> - In each actions the scope is applied. By default is :all.
+      #
+      # * <tt>:except</tt> - In each actions the scope is not applied. By default is :none.
+      #
+      # * <tt>:key</tt> - The key in the params hash expected to find the scope.
+      #                   Defaults to the scope name.
+      #
+      # * <tt>:default</tt> - Default value for the scope. Whenever supplied the scope
+      #                       is always called. This is useful to add easy pagination!
+      #
+      def has_scope(*scopes)
+        options = scopes.extract_options!
+
+        options.symbolize_keys!
+        options.assert_valid_keys(:on, :boolean, :key, :only, :except, :default)
+
+        acts_as_has_scopes!
+
+        scope_target  = options.delete(:on) || @@_parent_block_name || self.resources_configuration[:self][:instance_name]
+        target_config = self.scopes_configuration[scope_target.to_sym] ||= {}
+
+        scopes.each do |scope|
+          target_config[scope]         ||= {}
+          target_config[scope][:key]     = options[:key] || scope
+          target_config[scope][:only]    = Array(options[:only])
+          target_config[scope][:except]  = Array(options[:except])
+          target_config[scope][:boolean] = options[:boolean] if options.key?(:boolean)
+          target_config[scope][:default] = options[:default] if options.key?(:default)
+        end
+      end
+
+      # Load scopes from another controller into the current controller.
+      #
+      # You can give :on as option if you want to load just a set of the another
+      # controller scope.
+      #
+      #   class TasksController < InheritedResources::Base
+      #     belongs_to :project
+      #     load_scopes_from CompaniesController                 # load all scopes
+      #     load_scopes_from ProjectsController, :on => :project # load scopes that apply on :project
+      #   end
+      #
+      # Whenever called inside a belongs to block, the :on value is guessed:
+      #
+      #   class TasksController < InheritedResources::Base
+      #     belongs_to :project do
+      #       load_scopes_from ProjectsController # load scopes that apply on :project
+      #     end
+      #
+      #     load_scopes_from CompaniesController  # load all companies controller scopes
+      #   end
+      #
+      def load_scopes_from(scopes_controller, options={})
+        to_merge = if on = options.delete(:on) || @@_parent_block_name
+          scopes_controller.send(:scopes_configuration).slice(on)
+        else
+          scopes_controller.send(:scopes_configuration)
+        end
+
+        acts_as_has_scopes! # Add the module before merging scopes.
+
+        self.scopes_configuration.deep_merge!(to_merge)
+      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!
 
@@ -309,21 +274,19 @@ module InheritedResources #:nodoc:
         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?
+        raise ArgumentError, 'You cannot define multiple associations with options: #{options.keys.inspect} to belongs to.' 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.parents_symbols << :polymorphic unless self.parents_symbols.include?(:polymorphic)
             self.resources_configuration[:polymorphic][:symbols]   << symbol
             self.resources_configuration[:polymorphic][:optional] ||= optional
           else
@@ -333,51 +296,84 @@ module InheritedResources #:nodoc:
           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[: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[:finder]          = options.delete(:finder) || :find
+          config[:route_name]      = options.delete(:route_name) || symbol
         end
 
-        # Regenerate url helpers unless block is given
+        # Regenerate url helpers only once when blocks are given
         if block_given?
-          class_eval(&block)
-        else
-          InheritedResources::UrlHelpers.create_resources_url_helpers!(self)
+          raise ArgumentError, "You cannot define multiple associations and give a block to belongs_to." if symbols.size > 1
+
+          unless @@_parent_block_name
+            @@_parent_block_name = symbols.first
+            class_eval(&block)
+            @@_parent_block_name = nil
+          else
+            class_eval(&block)
+          end
         end
+
+        InheritedResources::UrlHelpers.create_resources_url_helpers!(self) unless @@_parent_block_name
       end
       alias :nested_belongs_to :belongs_to
 
-    private
+      # 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
 
-      # Defines this controller as singleton.
-      # You can call this method to define your controller as singleton.
+      # A quick method to declare singleton belongs to.
       #
-      def acts_as_singleton!
-        unless self.singleton
-          self.singleton = true
+      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
 
-      # Defines this controller as polymorphic.
-      # Do not call this method on your own.
-      #
-      def acts_as_polymorphic!
-        unless self.parents_symbols.include? :polymorphic
+      def acts_as_polymorphic! #:nodoc:
+        unless self.parents_symbols.include?(:polymorphic)
           include PolymorphicHelpers
-          helper_method :parent, :parent_type, :parent_class
+          helper_method :parent, :parent_type, :parent_class, :parent?
+        end
+      end
+
+      def acts_as_has_scopes! #:nodoc:
+        if self.scopes_configuration.empty?
+          include HasScopeHelpers
+          helper_method :current_scopes
         end
       end
 
-      # Initialize resources class accessors by creating the accessors
-      # and setting their default values.
+      # Initialize resources class accessors and set their default values.
       #
-      def initialize_resources_class_accessors!(base)
+      def initialize_resources_class_accessors!(base) #:nodoc:
         # Add and protect class accessors
         base.class_eval do
+          @@_parent_block_name = nil # Initialize parent flag
           metaklass = (class << self; self; end)
 
           RESOURCES_CLASS_ACCESSORS.each do |cattr|
@@ -411,9 +407,9 @@ module InheritedResources #:nodoc:
         namespaces = base.controller_path.split('/')[0..-2]
         config[:route_prefix] = namespaces.join('_') unless namespaces.empty?
 
-        # Initialize polymorphic, singleton and belongs_to parameters
-        base.singleton           = false
-        base.parents_symbols     = []
+        # Initialize polymorphic, singleton, scopes and belongs_to parameters
+        base.parents_symbols      = []
+        base.scopes_configuration = {}
         base.resources_configuration[:polymorphic] = { :symbols => [], :optional => false }
 
         # Create helpers

data/lib/inherited_resources/dumb_responder.rb

@@ -1,9 +1,9 @@
-# = Dumb Responder
-#
-# This responder discards all messages sent to him.
-#
-module InheritedResources #:nodoc:
-  class DumbResponder #:nodoc:
+module InheritedResources
+  # = Dumb Responder
+  #
+  # This responder discards all messages sent to him.
+  #
+  class DumbResponder
 
     instance_methods.each do |m|
       undef_method m unless m =~ /^__/
@@ -11,6 +11,7 @@ module InheritedResources #:nodoc:
 
     # This is like a good husband, he will just listen everything that his wife
     # says (which is a lot) without complaining. :)
+    #
     def method_missing(*args)
       nil
     end