README.rdoc in inherited_resources-1.1.2 vs README.rdoc in inherited_resources-1.2.0

- old
+ new

@@ -3,23 +3,36 @@ 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: +code by following fat models and skinny controllers convention. There are +two screencasts available besides this README: +http://railscasts.com/episodes/230-inherited-resources http://akitaonrails.com/2009/09/01/screencast-real-thin-restful-controllers-with-inherited-resources -== Rails 3 +== Installation +=== Rails 3 + Inherited Resources master branch is now supports Rails 3 and is NOT backward compatible. -You can install it as: +You can let bundler to install Inherited Resources by adding this line to your application's Gemfile: - sudo gem install inherited_resources --version=1.1.1 + gem 'inherited_resources', '~> 1.2' +And then execute: + + bundle install + +Or install it yourself as: + + gem install inherited_resources --version=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: @@ -36,11 +49,11 @@ http://github.com/plataformatec/has_scope And can be installed as: - sudo gem install has_scope + 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 @@ -49,28 +62,17 @@ http://github.com/plataformatec/responders And it can be installed as: - sudo gem install responders + 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 @@ -277,10 +279,29 @@ 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. +== Smart redirects + +Although the syntax above is a nice shortcut, you won't need to do it frequently +because (since version 1.2) Inherited Resources has smart redirects. Redirects +in actions calculates depending on the existent controller methods. + +Redirects in create and update actions calculates in following order resource_url, +collection_url, parent_url (which we are going to see later), root_url. Redirect +in destroy action calculate in following order collection_url, parent_url, root_url. + +Example: + + class ButtonsConntroller < InheritedResources::Base + belong_to :window + actions :all, :except => [:show, :index] + end + +This controller redirect to parent window after all CUD actions. + == 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 @@ -292,28 +313,10 @@ 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: @@ -397,11 +400,11 @@ == 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 ProjectsController < InheritedResources::Base + 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: @@ -433,10 +436,24 @@ # singleton_belongs_to :project end It will deal with everything again and hide the action :index from you. +== Namespaced Controllers + +Namespaced controllers works out the box. + + class Forum::PostsController < InheritedResources::Base + end + +Inherited Resources prioritizes the default resource class for the namespaced controller in +this order: + + Forum::Post + ForumPost + Post + == URL Helpers When you use InheritedResources it creates some URL helpers. And they handle everything for you. :) @@ -475,9 +492,46 @@ 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). + +== Custom actions + +Since version 1.2, Inherited Resources allows you to define custom actions in controller: + + class ButtonsController < InheritedResources::Base + custom_actions :resource => :delete, :collection => :search + end + +This code creates delete and search actions in controller (they behaves like show and +index actions accordingly). Also, it will produce delete_resource_{path,url} and +search_resources_{path,url} url helpers. + +== What about views? + +Sometimes just DRY the controllers is not enough, if you need to DRY up your views, +check this Wiki page: + +https://github.com/josevalim/inherited_resources/wiki/Views-Inheritance + +== 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 == Bugs and Feedback If you discover any bugs or want to drop a line, join us in the mailing list: