josevalim-inherited_resources 0.6.3 → 0.7.0

data/CHANGELOG

@@ -1,3 +1,12 @@
+# Version 0.7
+
+* Added has_scope to controller (an interface for named_scopes).
+* Added polymorphic_belongs_to, optional_belongs_to and singleton_belongs_to
+  as quick methods.
+* Only load belongs_to, singleton and polymorphic helpers if they are actually
+  required. base_helpers, class_methods, dumb_responder and url_helpers are loaded
+  when you inherited from base for the first time.
+
 # Version 0.6
 
 * Ensure that the default template is not rendered if the default_template_format

data/README

@@ -1,6 +1,6 @@
 Inherited Resources
 License: MIT
-Version: 0.6.3
+Version: 0.7.0
 
 You can also read this README in pretty html at the GitHub project Wiki page:
 
@@ -36,10 +36,8 @@ If you want it as plugin, just do:
 rspec-rails <= 1.1.12 known bug
 -------------------------------
 
-InheritedResources has a known bug with rspec-rails when using blocks inside
-actions. This is fixed in Rspec >= 1.2.0. But if you have to use 1.1.12, you
-InheritedResources ships with a patch. To apply it, just put the line below on
-your spec_helper.rb after loading rspec and rspec-rails:
+InheritedResources has a known bug with rspec-rails. Please upgrade your rspec
+version or use the fix which ships with InheritedResources:
 
   require 'inherited_resources/spec'
 
@@ -69,11 +67,9 @@ You can also specify them based per action:
      respond_to :iphone, :except => [ :edit, :update ]
    end
 
-Let's take a request on create with :rjs as example of how it works. After the
-action is processed, it will check if the view "projects/create.js.rjs" exist.
-If it does exist, it will render it, otherwise it will check if the resource
-@project respond to :to_js. If it is true, it will render the result of :to_js,
-otherwise it will render a 404.
+For each request, it first checkes if the "controller/action.format" file is
+available (for example "projects/create.xml") and if it's not, it checks if
+the resource respond to :to_format (in this case, :to_xml). Otherwise returns 404.
 
 Another option is to specify which actions the controller will inherit from
 the InheritedResources::Base:
@@ -100,12 +96,9 @@ on index actions.
 Overwriting defaults
 --------------------
 
-Now that you learned the default behavior and basic configuration, let's see
-how to extend it.
-
-Some people usually have an AccountsController to deal with all account
-management while the resource is an User. So you can overwrite the resource class,
-collection name and instance name just doing:
+Whenever you inherit from InheritedResources, several defaults are assumed.
+For example you can have an AccountsController to account management while the
+resource is an User:
 
    class AccountsController < InheritedResources::Base
      defaults :resource_class => User, :collection_name, 'users', :instance_name => 'user'
@@ -122,10 +115,13 @@ different route prefix, you can do the following:
      defaults :route_prefix => 'admin'
    end
 
-Then your named routes will be: 'admin_people_url', 'admin_person_url' and so on.
+Then your named routes will be: 'admin_people_url', 'admin_person_url' instead
+of 'administrators_people_url' and 'administrators_person_url'.
 
-Further extensions is done by overwriting two methods. Let's suppose you want
-to add pagination to your projects collection:
+If you want to customize how resources are retrieved you can overwrite
+collection and resource methods. The first is called on index action and the
+second on all other actions. Let's suppose you want to add pagination to your
+projects collection:
 
    class ProjectsController < InheritedResources::Base
      protected
@@ -134,38 +130,14 @@ to add pagination to your projects collection:
        end
    end
 
-In this case you could just have done:
-
-   class ProjectsController < InheritedResources::Base
-     protected
-       def collection
-         @projects ||= Project.paginate(params[:page]).all
-       end
-   end
+The end_of_association_chain returns your resource after nesting all associations
+and scopes (more about this below).
 
-But you should get used if end_of_association_chain. When you have nested
-resources it's very handy and it will deal with all nesting stuff. It was first
-introduced in resource_controller by Jamis Golick and we will talk more about it
-soon.
-
-On the other hand, if you just added pretty urls for in your ProjectsController
-(/projects/my-project-name), you can overwrite how projects are being found by:
-
-   class ProjectsController < InheritedResources::Base
-     protected
-       def resource
-         @project ||= end_of_association_chain.find_by_title!(params[:title])
-       end
-   end
-
-And now since you is acquainted to end_of_association_chain let's meet its
-twin brother: begin_of_association_chain.
-
-It's mostly used when you want to create resources based on the @current_user.
-In such cases, you don't have your @current_user in the url, but in the session.
-
-This is usually when you have urls like "account/projects" and you have to do
+InheritedResources also introduces another method called begin_of_association_chain.
+It's mostly used when you want to create resources based on the @current_user and
+you have urls like "account/projects". In such cases, so you have to do
 @current_user.projects.find or @current_user.projects.build in your actions.
+
 You can deal with it just doing:
 
    class ProjectsController < InheritedResources::Base
@@ -192,9 +164,8 @@ root url instead of redirecting to projects url. You just have to do:
 You are opening your action and giving the parent action a new behavior. No
 tricks, no DSL, just Ruby.
 
-On the other hand, I have to agree that calling super is the right thing but
-is not very readable. That's why all methods have aliases. So this is
-equivalent:
+On the other hand, I have to agree that calling super is not very readable.
+That's why all methods have aliases. So this is equivalent:
 
    class ProjectsController < InheritedResources::Base
      def destroy
@@ -204,7 +175,7 @@ equivalent:
      end
    end
 
-Even more, since most of the times that you change a :create, :update or :destroy
+Even more, since most of the times when you change a :create, :update or :destroy
 action is because you want to to change to where it redirects, a shortcut is
 provided. So you can do:
 
@@ -225,9 +196,8 @@ but you don't want to create a before filter for it:
      end
    end
 
-Yeap, that simple! The nice part is since you already set the instance variable
-@project, it will not do it again and overwrite your @project with something
-special. :)
+Yes, that simple! The nice part is since you already set the instance variable
+@project, it will not build a project again.
 
 Before we finish this topic, we should talk about one more thing: "success/failure
 blocks". Let's suppose that when we update our project, in case of failure, we
@@ -245,8 +215,7 @@ Our first attempt to do this would be:
      end
    end
 
-Looks to verbose, right? (Maybe it reminds you of something! :P)
-But this is Ruby and we can actually do:
+Looks to verbose, right? We can actually do:
 
    class ProjectsController < InheritedResources::Base
      def update
@@ -271,11 +240,10 @@ order:
    flash.controller_name.action_name.status
    flash.actions.action_name.status
 
-If none is available, a default message in english set. Let's have a break from
-projects and talk about CarsController. So in a create action, it will check for
-flash messages in the following order:
+If none is available, a default message in english set. In a create action
+on projects controller, it will search for:
 
-   flash.cars.create.status
+   flash.projects.create.status
    flash.actions.create.status
 
 The status can be :notice (when the object can be created, updated
@@ -291,34 +259,33 @@ is also localized and it means you can set:
          notice: "Hooray! {{resource_name}} was successfully created!"
 
 It will replace {{resource_name}} by the human name of the resource class,
-which is "Car" in this case.
+which is "Project" in this case.
 
-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:
+But sometimes, flash messages are not that simple. Sometimes you want to say
+the title of the project while updating a project. Well, that's easy also:
 
    flash:
-     cars:
+     projects:
        update:
-         notice: "Hooray! You just tuned your {{car_brand}}!"
+         notice: "Hooray! The project "{{project_title}}" was updated!"
 
-Since :car_name is not available for interpolation by default, you have
+Since :project_title is not available for interpolation by default, you have
 to overwrite interpolation_options.
 
    def interpolation_options
-     { :car_brand => @car.brand }
+     { :project_title => @project.title }
    end
 
 Then you will finally have:
 
-   'Hooray! You just tuned your Aston Martin!'
+   "Hooray! The project "Plataforma" was updated!"
 
-If your controller is namespaced, for example Rars::CarsController, the
+If your controller is namespaced, for example Admin::ProjectsController, the
 messages will be checked in the following order:
 
-   flash.rare.cars.create.notice
-   flash.rare.actions.create.notice
-   flash.cars.create.notice
+   flash.admin.projects.create.notice
+   flash.admin.actions.create.notice
+   flash.projects.create.notice
    flash.actions.create.notice
 
 Belongs to
@@ -332,16 +299,15 @@ TasksController and do:
    end
 
 belongs_to accepts several options to be able to configure the association.
-Remember that our projects have pretty urls? So if you thought that url like
-/projects/:project_title/tasks would be a problem, I can assure you it won't:
+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.
-For more information, check the lib/inherited_resources/class_method.rb file
-for more customization. :)
+Check the lib/inherited_resources/class_methods.rb for more.
 
 Nested belongs to
 -----------------
@@ -354,23 +320,95 @@ you have to for security reasons. So this is an example of how you can do it:
      nested_belongs_to :project, :task
    end
 
-nested_belongs_to is actually just an alias to belongs_to created to make clear
-what is happening. You can also declare nested_belongs_to like this:
+If you need to configure any of these belongs to, you can nested them using blocks:
 
    class CommentsController < InheritedResources::Base
-     belongs_to :project do
+     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 CommentsConroller < InheritedResources::Base
+     belongs_to :project
+     belongs_to :task
+   end
+
+In other words, the code above is the same as calling nested_belongs_to.
+
+Has Scope
+---------
+
+InheritedResources besides belongs_to also speaks named_scope. Let's have a
+break from projects and talk about graduations. Your model:
+
+  class Graduation < ActiveRecord::Base
+    named_scope :featured, :conditions => { :featured => true }
+    named_scope :by_degree, proc {|degree| { :conditions => { :degree => degree } } }
+    named_scope :limit, proc{|limit| :limit => limit.to_i }
+  end
+
+Your controller:
+
+  class GraduationsController < InheritedResources::Base
+    has_scope :featured, :boolean => true, :only => :index
+    has_scope :by_degree
+    has_scope :limit, :default => 10
+  end
+
+Then for each request:
+
+  /graduations
+  #=> acts like a normal request, but returning 10 resources
+
+  /graduations?featured=true
+  #=> calls the featured named scope and bring 10 featured graduations
+
+  /graduations?featured=true&by_degree=phd&limit=20
+  #=> brings 20 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
+    has_scope :limit, :on => :graduation, :default => 10
+  end
+
+You can also do this inside the belongs to block:
+
+  class StudentsController < InheritedResources::Base
+    belongs_to :graduation do
+      has_scope :featured,  :boolean => true, :only => :index
+      has_scope :by_degree, :only => :index
+      has_scope :limit, :default => 10
+    end
+  end
+
+Or even better, you can load the scopes from another controller:
+
+  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.
+
 Polymorphic belongs to
 ----------------------
 
-Now let's go even further. Our Projects is getting some Files and Messages
-besides Tasks, and they are all commentable:
+Now let's go back to Projects which can now have Files, Messages and Tasks, and
+they are all commentable:
 
    class CommentsController < InheritedResources::Base
      belongs_to :task, :file, :message, :polymorphic => true
+     # polymorphic_belongs_to :task, :file, :message
    end
 
 You can even use it with nested resources:
@@ -388,29 +426,23 @@ When using polymorphic associations, you get some free helpers:
    parent_class    #=> Task
    parent          #=> @task
 
-Polymorphic controller is another great idea by James Golick and he also uses
-that on resource_controller.
-
 Optional belongs to
 -------------------
 
-Let's take another break from Projects. Let's suppose that we are now building
-a store, which sell products.
-
-On the website, we can show all products, but also products scoped to
-categories, brands, users, etc. In this case case, the association is optional,
-and we deal with it in the following way:
+Later you decide to create a view to show all comments, independing they belong
+to a task, file or message. You canm reuse your previous controller just doing:
 
-  class ProductsController < InheritedResources::Base
-    belongs_to :category, :brand, :user, :polymorphic => true, :optional => true
+  class ProjectsController < InheritedResources::Base
+    belongs_to :task, :file, :message, :optional => true
+    # optional_belongs_to :task, :file, :message
   end
 
 This will handle all those urls properly:
 
-  /products/1
-  /categories/2/products/5
-  /brands/10/products/3
-  /user/13/products/11
+  /comment/1
+  /tasks/2/comment/5
+  /files/10/comment/3
+  /messages/13/comment/11
 
 This is treated as a special type of polymorphic associations, thus all helpers
 are available. As you expect, when no parent is found, the helpers return:
@@ -432,6 +464,7 @@ option.
 
    class ManagersController < InheritedResources::Base
      belongs_to :project, :singleton => true
+     # singleton_belongs_to :project
    end
 
 It will deal with everything again and hide the action :index from you.
@@ -475,12 +508,6 @@ Another nice thing is that those urls are not guessed during runtime. They are
 all created when your application is loaded (except for polymorphic
 associations, that relies on Rails polymorphic_url).
 
-What's next
------------
-
-I'm working on generators and some nice things to speed up and make easier
-your controllers tests with mocking and stubs. :)
-
 Bugs and Feedback
 -----------------
 

data/lib/inherited_resources/base.rb

@@ -1,196 +1,22 @@
-# = Inheriting
-#
-# To use InheritedResources you have to inherit from InheritedResources::Base
-# class. This class have all Rails REST actions defined (index, show, new, edit
-# update, create and destroy). The following definition is the same as a Rails
-# scaffolded controller:
-#
-#   class ProjectController < InheritedResources::Base
-#   end
-#
-# All actions are defined, check it!
-#
-# The next step is to define which mime types this controller provides:
-#
-#   class ProjectController < InheritedResources::Base
-#     respond_to :html, :xml, :json
-#   end
-#
-# You just said that this controller will respond to :html, :xml and :json. You
-# can also specify it based on actions:
-#
-#   class ProjectController < InheritedResources::Base
-#     respond_to :html, :xml, :json
-#     respond_to :js, :only => :create
-#     respond_to :csv, :except => [ :destroy ]
-#   end
-#
-# How it works is simple. Let's suppose you have a json request on the action
-# show. It will first try to render "projects/show.json.something". If it can't
-# be found, it will call :to_json in the resource, which in this case is
-# @project.
-#
-# If the resource @project doesn't respond to :to_json, we will render a 404
-# Not Found.
-#
-# If you don't want to inherit all actions from InheritedResources::Base, call
-# actions method with the actions you want to inherit:
-#
-#   class ProjectController < InheritedResources::Base
-#     actions :index, :show, :new, :create, :edit, :update
-#   end
-#
-# Or:
-#
-#   class ProjectController < InheritedResources::Base
-#     actions :all, :except => :destroy
-#   end
-#
-# = Extending the default behaviour
-#
-# Let's suppose that after destroying a project you want to redirect to your
-# root url instead of redirecting to projects url. You just have to do:
-#
-#   class ProjectController < InheritedResources::Base
-#     def destroy
-#       super do |format|
-#         format.html { redirect_to root_url }
-#       end
-#     end
-#   end
-#
-# super? Yes, we agree that calling super is the right thing but it does not
-# look nice. That's why all methods have aliases. So this is equivalent:
-#
-#   class ProjectController < InheritedResources::Base
-#     def destroy
-#       destroy! do |format|
-#         format.html { redirect_to root_url }
-#       end
-#     end
-#   end
-#
-# Even more, since most of the times that you change a :create, :update or :destroy
-# action is because you want to to change to where it redirects, a shortcut is
-# provided. So you can do:
-#
-#   class ProjectsController < InheritedResources::Base
-#     def destroy
-#       destroy!(root_url)
-#     end
-#   end
-#
-# Since this is actually Ruby (and not a new DSL), if you want to do something
-# before creating the project that is to small to deserve a before_filter, you
-# could simply do:
-#
-#   class ProjectController < InheritedResources::Base
-#     def create
-#       # do something different!
-#       create!
-#     end
-#   end
-#
-# And as instance variables are shared you can do more nice things.
-# Let's suppose you want to create a project based on the current user:
-#
-#   class ProjectController < InheritedResources::Base
-#     def create
-#       @project = @current_user.projects.build(params[:project])
-#       create!
-#     end
-#   end
-#
-# When you call create! the instance variable @project is already defined,
-# so the method won't instanciate it again.
-#
-# The great thing is that we are not using blocks or nothing in special. We are
-# just inheriting and calling the parent (super). You can extend even more
-# without using blocks, please check helpers.rb for more info.
-#
-# = Flash and I18n
-#
-# Flash messages are changed through I18n API. If you have a ProjectsController,
-# when a resource is updated with success, it will search for messages in the
-# following order:
-#
-#   'flash.projects.update.notice'
-#   'flash.actions.update.notice'
-#
-# If none of them are not available, it will show the default message:
-#
-#   Project was successfully updated.
-#
-# The message will be set into flash[:notice].
-# Messages can be interpolated, so you can do the following in your I18n files:
-#
-#   flash:
-#     actions:
-#       update:
-#         notice: "Hooray! {{resource_name}} was updated with success!"
-#
-# It will replace {{resource_name}} by Project.human_name, which is also localized
-# (check http://rails-i18n.org/wiki/pages/i18n-rails-guide for more info).
-#
-# But sometimes, flash messages are not that simple. You might want to say the
-# the name of the project when it's updated. Well, that's easy also:
-#
-#   flash:
-#     projects:
-#       update:
-#         notice: "Dear manager, {{project_name}} was successfully updated!"
-#
-# Since :project_name is not available for interpolation by default, you
-# have to overwrite interpolation_options method on your controller.
-#
-#   def interpolation_options
-#     { :project_name => @project.quoted_name }
-#   end
-#
-# Then you will finally have:
-#
-#   'Dear manager, "Make Rails Scale" was successfully updated!'
-#
-# Success messages appear on :create, :update and :destroy actions. Failure
-# messages appear only on :create and :update.
-#
-# = Changing assumptions
-#
-# When you inherit from InheritedResources::Base, we make some assumptions on
-# what is your resource_class, instance_name and collection_name.
-#
-# You can change those values by calling the class method defaults:
-#
-#   class PeopleController < InheritedResources::Base
-#     defaults :resource_class => User, :instance_name => 'user', :collection_name => 'users'
-#   end
-#
-# Namespaced controllers work out of the box, but if you need to specify a
-# different route prefix, you can do the following:
-#
-#   class Administrators::PeopleController < InheritedResources::Base
-#     defaults :route_prefix => 'admin'
-#   end
-#
-# Then your named routes will be: 'admin_people_url', 'admin_person_url' and
-# so on.
-#
-# Further customizations can be done replacing some methods. Check
-# base_helpers.rb file for more information.
-
-# Let's require all needed files here. We are still on time to eager load
-# everything on multithreaded environments.
+# Whenever Base is required, we eager load the base files. belongs_to, polymorphic
+# and singleton helpers are loaded on demand.
 require File.dirname(__FILE__) + '/base_helpers.rb'
-require File.dirname(__FILE__) + '/belongs_to_helpers.rb'
 require File.dirname(__FILE__) + '/class_methods.rb'
 require File.dirname(__FILE__) + '/dumb_responder.rb'
-require File.dirname(__FILE__) + '/polymorphic_helpers.rb'
-require File.dirname(__FILE__) + '/singleton_helpers.rb'
 require File.dirname(__FILE__) + '/url_helpers.rb'
 
 module InheritedResources
-  RESOURCES_ACTIONS = [ :index, :show, :new, :edit, :create, :update, :destroy ] unless self.const_defined? "RESOURCES_ACTIONS"
-
+  RESOURCES_ACTIONS = [ :index, :show, :new, :edit, :create, :update, :destroy ] unless self.const_defined?(:RESOURCES_ACTIONS)
+
+  # = Base
+  #
+  # This is the base class that holds all actions. If you see the code for each
+  # action, they are quite similar to Rails default scaffold.
+  #
+  # To change your base behavior, you can overwrite your actions and call super,
+  # call <tt>default</tt> class method, call <<tt>actions</tt> class method
+  # or overwrite some helpers in the base_helpers.rb file.
+  #
   class Base < ::ApplicationController
     unloadable
 
@@ -199,9 +25,9 @@ module InheritedResources
 
     helper_method :collection_url, :collection_path, :resource_url, :resource_path,
                   :new_resource_url, :new_resource_path, :edit_resource_url, :edit_resource_path,
-                  :resource, :collection, :resource_class, :parent?
+                  :resource, :collection, :resource_class
 
-    def self.inherited(base)
+    def self.inherited(base) #:nodoc:
       base.class_eval do
         # Make all resources actions public
         public *RESOURCES_ACTIONS