karsthammer-inherited_resources 1.1.2

data/CHANGELOG

@@ -0,0 +1,119 @@
+# Version 1.1
+
+* Rails 3 compatible
+
+# Version 1.0
+
+* responders was removed from InheritedResources core and is a dependency. To install it, please do:
+
+    sudo gem install responders
+
+* has_scope was removed from InheritedResources core and is now available as a standalone gem.
+  To install it, please do:
+
+    sudo gem install has_scope
+  
+# Version 0.9
+
+* Allow dual blocks in destroy;
+* Added :if and :unless to has_scope (thanks to Jack Danger);
+* Added create_resource, update_resource and delete_resource hooks (thanks to Carlos Antonio da Silva);
+* Backported ActionController::Responder from Rails 3;
+* Added parent_url helper;
+* Added association_chain helper (as suggested by http://github.com/emmanuel);
+
+# Version 0.8
+
+* Fixed a small bug on optional belongs to with namespaced controllers.
+* Allow a parameter to be given to collection_url in polymorphic cases to replace
+  the parent.
+* Allow InheritedResources to be called without inheritance.
+* Ensure that controllers that inherit from a controller with InheritedResources
+  works properly.
+
+# Version 0.7
+
+* Allow procs as default value in has scope to be able to use values from session, for example.
+* Allow blocks with arity 0 or -1 to be given as the redirect url:
+
+    def destroy
+      destroy!{ project_url(@project) }
+    end
+
+* Allow interpolation_options to be set in the application controller.
+* 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
+  is not accepted. This is somehow related with the security breach report:
+
+  http://www.rorsecurity.info/journal/2009/4/24/hidden-actions-render-templates.html
+
+  IR forbids based on mime types. For example: respond_to :html, :except => :index
+  ensures that the index.html.erb view is not rendered, making your IR controllers
+  safer.
+
+* Fixed a bug that happens only when format.xml is given to blocks and then it
+  acts as default, instead of format.html.
+* Fixed a strange bug where when you have create.html.erb or update.html.erb,
+  it makes IE6 and IE7 return unprocessable entity (because they send Mime::ALL).
+* Stop rescueing any error when constantizing the resource class and allow
+  route_prefix to be nil.
+* Cleaned up tests and responder structure. Whenever you pass a block to aliases
+  and this block responds to the request, the other blocks are not parsed improving performance.
+* [BACKWARDS INCOMPATIBLE] By default, Inherited Resources respond only :html requests.
+* Added a quick way to overwrite the redirect to url in :create, :update and :destroy.
+
+# Version 0.5
+
+* Decoupled routes name from :instance_name and :collection_name. This way we
+  have more flexibility. Use route_instance_name and route_collection_name to
+  to change routes.
+* Avoid calling human_name on nil when a resource class is not defined.
+* Only call I18n if it's defined.
+
+# Version 0.4
+
+* Dealing with namespaced controllers out of the box.
+* Added support to namespaced routes through :route_prefix.
+* Added fix when resource_url is not defined.
+* Added better handling for namespaced controllers.
+* Added flash messages scoped by namespaced controllers.
+* Deprecated {{resource}} in I18n, use {{resource_name}} instead.
+* rspec bug fix is not automatically required anymore. User has to do it
+  explicitly.
+* Added a file which fix a rspec bug when render is called inside a method
+  which receives a block.
+* parent? does not take begin_of_association_chain into account anymore
+* Added options to url helpers.
+* Added :optional to belongs_to associations. It allows you to deal with
+  categories/1/products/2 and /products/2 with just one controller.
+* Cleaned up tests.
+
+# Version 0.3
+
+* Minor bump after three bug fixes.
+* Bug fix when showing warning of constant redefinition.
+* Bug fix with ApplicationController not being unloaded properly on development.
+* Bug fix when having root singleton resources. Calling collection_url would
+  raise "NoMethodError _url", not it will call root_url.
+* More comments on UrlHelpers.
+
+# Version 0.2
+
+* Bug fix when ApplicationController is already loaded when we load respond_to.
+* Added support success/failure blocks.
+* Eager loading of files to work properly in multithreaded environments.
+
+# Version 0.1
+
+* Added more helper_methods.
+* Added Rails 2.3.0 and changed tests to work with ActionController::TestCase.
+* First release. Support to I18n, singleton controllers, polymorphic
+controllers, belongs_to, nested_belongs_to and url helpers.

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 José Valim http://blog.plataformatec.com.br
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.rdoc

@@ -0,0 +1,516 @@
+== Inherited Resources
+
+Inherited Resources speeds up development by making your controllers inherit
+all restful actions so you just have to focus on what is important. It makes
+your controllers more powerful and cleaner at the same time.
+
+Plus, making your controllers follow a pattern, it helps you to write better
+code by following fat models and skinny controllers convention. There is
+a screencast made by Fabio Akita about its features:
+
+http://akitaonrails.com/2009/09/01/screencast-real-thin-restful-controllers-with-inherited-resources
+
+=== What about views?
+
+Sometimes just DRY the controllers is not enough, a lot of the resources often share the same views, wouldn't it be nice to have view files DRY'ed too? You can! There are currently two projects do just that.
+
+==== Inherited Resources Views
+
+Inherited Resources Views is an extremely easy to use plugin to DRY the views associated with your inherited resources controllers. It is library-agnostic (it only depends on Inherited Resources) and it supports generating both erb and haml templates.
+
+Source: http://github.com/fredwu/inherited_resources_views
+
+==== Inherited Views
+
+Inherited Views is a thin addition to the Inherited Resources project adding default html views which can be later customized on a per controller basis or globally for your rails app. It depends on Inherited Resources, Formtastic and WillPaginate.
+
+Source: http://github.com/gregbell/inherited_views
+
+== Installation
+
+=== Rails 3
+
+Inherited Resources master branch is now supports Rails 3 and is NOT backward compatible.
+
+You can let bundler to install Inherited Resources by adding this line to your application's Gemfile:
+
+  gem 'inherited_resources', '1.1.2'
+
+And then execute:
+
+  bundle install 
+
+Or install it yourself as:
+
+  gem install inherited_resources --version=1.1.2
+
+=== Rails 2.3.x
+
+If you want to use the Rails 2.3.x version, you should install:
+
+  sudo gem install inherited_resources --version=1.0.6
+
+Or checkout from the v1.0 branch:
+
+  http://github.com/josevalim/inherited_resources/tree/v1.0
+
+== HasScope
+
+Since Inherited Resources 1.0, has_scope is not part of its core anymore.
+However, if you are using has_scope in your application, Inherited Resources
+will handle all the required hooks automatically.
+
+has_scope gem is available at:
+
+  http://github.com/plataformatec/has_scope
+
+And can be installed as:
+
+  sudo gem install has_scope
+
+== Responders
+
+Since Inherited Resources 1.0, responders are not part of its core anymore,
+but is set as Inherited Resources dependency and it's used by default by
+InheritedResources controllers. Be sure to check the documentation to see
+how it will change your application:
+
+  http://github.com/plataformatec/responders
+
+And it can be installed as:
+
+  sudo gem install responders
+
+Using responders will set the flash message to :notice and :alert. You can change
+that through the following configuration value:
+
+  InheritedResources.flash_keys = [ :success, :failure ]
+
+== Rspec known bug
+
+Rspec monkey patches a couple of controller methods in a way that Controller specs
+(with integrate views true or false) and Inherited Resources are not compatible.
+
+However, since your controllers inherit from InheritedResources::Base, they are
+already unit-tested in the plugin, so there is no need to test them again in Rspec.
+
+You should test things like url redirection and associations in your integration
+specs.
+
+== Basic Usage
+
+To use Inherited Resources you just have to inherit (duh) it:
+
+    class ProjectsController < InheritedResources::Base
+    end
+
+And all actions are defined and working, check it! Your projects collection
+(in the index action) is still available in the instance variable @projects
+and your project resource (all other actions) is available as @project.
+
+The next step is to define which mime types this controller provides:
+
+    class ProjectsController < InheritedResources::Base
+      respond_to :html, :xml, :json
+    end
+
+You can also specify them based per action:
+
+    class ProjectsController < InheritedResources::Base
+      respond_to :html, :xml, :json
+      respond_to :js, :only => :create
+      respond_to :iphone, :except => [ :edit, :update ]
+    end
+
+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:
+
+    class ProjectsController < InheritedResources::Base
+      actions :index, :show, :new, :create
+    end
+
+Or:
+
+    class ProjectsController < InheritedResources::Base
+      actions :all, :except => [ :edit, :update, :destroy ]
+    end
+
+In your views, you will get the following helpers:
+
+    resource        #=> @project
+    collection      #=> @projects
+    resource_class  #=> Project
+
+As you might expect, collection (@projects instance variable) is only available
+on index actions.
+
+If for some reason you cannot inherit from InheritedResources::Base, you can
+call inherit_resources in your controller class scope:
+
+    class AccountsController < ApplicationController
+      inherit_resources
+    end
+
+== Overwriting defaults
+
+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'
+    end
+
+In the case above, in your views you will have @users and @user variables, but
+the routes used will still be accounts_url and account_url. If you plan also to
+change the routes, you can use :route_collection_name and :route_instance_name.
+
+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' instead
+of 'administrators_people_url' and 'administrators_person_url'.
+
+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
+        def collection
+          @projects ||= end_of_association_chain.paginate(:page => params[:page])
+        end
+    end
+
+The end_of_association_chain returns your resource after nesting all associations
+and scopes (more about this below).
+
+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, 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
+      protected
+        def begin_of_association_chain
+          @current_user
+        end
+    end
+
+== Overwriting actions
+
+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 ProjectsController < InheritedResources::Base
+      def destroy
+        super do |format|
+          format.html { redirect_to root_url }
+        end
+      end
+    end
+
+You are opening your action and giving the parent action a new behavior. 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
+        destroy! do |format|
+          format.html { redirect_to root_url }
+        end
+      end
+    end
+
+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:
+
+    class ProjectsController < InheritedResources::Base
+      def destroy
+        destroy!{ root_url }
+      end
+    end
+
+If you simply want to change the flash message for a particular action, you can
+pass the message to the parent action using the keys :notice and :alert (as you
+would with flash):
+
+    class ProjectsController < InheritedResources::Base
+      def create
+        create!(:notice => "Dude! Nice job creating that project.")
+      end
+    end
+
+You can still pass the block to change the redirect, as mentioned above:
+
+    class ProjectsController < InheritedResources::Base
+      def create
+        create!(:notice => "Dude! Nice job creating that project.") { root_url }
+      end
+    end
+
+Now let's suppose that before create a project you have to do something special
+but you don't want to create a before filter for it:
+
+    class ProjectsController < InheritedResources::Base
+      def create
+        @project = Project.new(params[:project])
+        @project.something_special!
+        create!
+      end
+    end
+
+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
+want to redirect to the project url instead of re-rendering the edit template.
+
+Our first attempt to do this would be:
+
+    class ProjectsController < InheritedResources::Base
+      def update
+        update! do |format|
+          unless @project.errors.empty? # failure
+            format.html { redirect_to project_url(@project) }
+          end
+        end
+     end
+    end
+
+Looks to verbose, right? We can actually do:
+
+    class ProjectsController < InheritedResources::Base
+      def update
+        update! do |success, failure|
+          failure.html { redirect_to project_url(@project) }
+        end
+      end
+    end
+
+Much better! So explaining everything: when you give a block which expects one
+argument it will be executed in both scenarios: success and failure. But If you
+give a block that expects two arguments, the first will be executed only in
+success scenarios and the second in failure scenarios. You keep everything
+clean and organized inside the same action.
+
+== Success and failure scenarios on destroy
+
+The destroy action can also fail, this usually happens when you have a
+before_destroy callback in your model which returns false. However, in
+order to tell InheritedResources that it really failed, you need to add
+errors to your model. So your before_destroy callback on the model should
+be something like this:
+
+    def before_destroy
+      if cant_be_destroyed?
+        errors.add(:base, "not allowed")
+        false
+      end
+    end
+
+== Some DSL
+
+For those DSL lovers, InheritedResources won't leave you alone. You can overwrite
+your success/failure blocks straight from your class binding. For it, you just
+need to add a DSL module to your application controller:
+
+    class ApplicationController < ActionController::Base
+      include InheritedResources::DSL
+    end
+
+And then you can rewrite the last example as:
+
+    class ProjectsController < InheritedResources::Base
+      update! do |success, failure|
+        failure.html { redirect_to project_url(@project) }
+      end
+    end
+
+== Belongs to
+
+Finally, our Projects are going to get some Tasks. Then you create a
+TasksController and do:
+
+    class TasksController < InheritedResources::Base
+      belongs_to :project
+    end
+
+belongs_to accepts several options to be able to configure the association.
+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.
+Check the lib/inherited_resources/class_methods.rb for more.
+
+== Nested belongs to
+
+Now, our Tasks get some Comments and you need to nest even deeper. Good
+practices says that you should never nest more than two resources, but sometimes
+you have to for security reasons. So this is an example of how you can do it:
+
+    class CommentsController < InheritedResources::Base
+      nested_belongs_to :project, :task
+    end
+
+If you need to configure any of these belongs to, you can nest them using blocks:
+
+    class CommentsController < InheritedResources::Base
+      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.
+
+== Polymorphic belongs to
+
+We can go even further. Let's suppose our Projects can now have Files, Messages
+and Tasks, and they are all commentable. In this case, the best solution is to
+use polymorphism:
+
+    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:
+
+    class CommentsController < InheritedResources::Base
+      belongs_to :project do
+        belongs_to :task, :file, :message, :polymorphic => true
+      end
+    end
+
+The url in such cases can be:
+
+    /project/1/task/13/comments
+    /project/1/file/11/comments
+    /project/1/message/9/comments
+
+When using polymorphic associations, you get some free helpers:
+
+    parent?         #=> true
+    parent_type     #=> :task
+    parent_class    #=> Task
+    parent          #=> @task
+
+Right now, Inherited Resources is limited and does not allow you
+to have two polymorphic associations nested.
+
+== Optional belongs to
+
+Later you decide to create a view to show all comments, independent if they belong
+to a task, file or message. You can reuse your polymorphic controller just doing:
+
+    class CommentsController < InheritedResources::Base
+      belongs_to :task, :file, :message, :optional => true
+      # optional_belongs_to :task, :file, :message
+    end
+
+This will handle all those urls properly:
+
+    /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:
+
+    parent?         #=> false
+    parent_type     #=> nil
+    parent_class    #=> nil
+    parent          #=> nil
+
+== Singletons
+
+Now we are going to add manager to projects. We say that Manager is a singleton
+resource because a Project has just one manager. You should declare it as
+has_one (or resource) in your routes.
+
+To declare an association as singleton, you just have to give the :singleton
+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.
+
+== URL Helpers
+
+When you use InheritedResources it creates some URL helpers.
+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
+    edit_resource_url(comment) #=>  /posts/1/comments/#{comment.to_param}/edit
+    collection_url             # => /posts/1/comments
+    parent_url                 # => /posts/1
+
+    # /projects/1/tasks
+    resource_url               # => /projects/1/tasks/#{@task.to_param}
+    resource_url(task)         # => /projects/1/tasks/#{task.to_param}
+    new_resource_url           # => /projects/1/tasks/new
+    edit_resource_url          # => /projects/1/tasks/#{@task.to_param}/edit
+    edit_resource_url(task)    # => /projects/1/tasks/#{task.to_param}/edit
+    collection_url             # => /projects/1/tasks
+    parent_url                 # => /projects/1
+
+    # /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
+    edit_resource_url(user)    # => /users/#{user.to_param}/edit
+    collection_url             # => /users
+    parent_url                 # => /
+
+Those urls helpers also accepts a hash as options, just as in named routes.
+
+    # /projects/1/tasks
+    collection_url(:page => 1, :limit => 10) #=> /projects/1/tasks?page=1&limit=10
+
+In polymorphic cases, you can also give the parent as parameter to collection_url.
+
+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).
+
+== Bugs and Feedback
+
+If you discover any bugs or want to drop a line, join us in the mailing list:
+
+http://groups.google.com/group/inherited_resources
+
+Copyright (c) 2009 José Valim http://blog.plataformatec.com.br
+See the attached MIT License.