added documentation for :as and :object in PartialRenderer

Signed-off-by: Mikel Lindsaar <raasdnil@gmail.com>

1 files changed, 32 insertions, 0 deletions

diff --git a/actionpack/lib/action_view/render/partials.rb b/actionpack/lib/action_view/render/partials.rb
index 92cdbfb3af..6ad40ad8d4 100644
--- a/actionpack/lib/action_view/render/partials.rb
+++ b/actionpack/lib/action_view/render/partials.rb
@@ -26,6 +26,36 @@ module ActionView
   # This would first render "advertiser/_account.erb" with @buyer passed in as the local variable +account+, then
   # render "advertiser/_ad.erb" and pass the local variable +ad+ to the template for display.
   #
+  # == The :as and :object options
+  #
+  # By default PartialRenderer uses the template name for the local name of the object passed into the template.
+  # These examples are effectively the same:
+  # 
+  #   <%= render :partial => "contract", :locals => { :contract  => @contract } %>
+  # 
+  #   <%= render :partial => "contract" %>
+  #
+  # By specifying the :as option we can change the way the local variable is namedin the template.
+  # These examples are effectively the same:
+  # 
+  #   <%= render :partial => "contract", :as => :agreement
+  # 
+  #   <%= render :partial => "contract", :locals => { :agreement => @contract }
+  #
+  # The :object option can be used to directly specify which object is rendered into the partial.
+  # 
+  # Revisiting a previous example we could have written this code.
+  # 
+  #   <%= render :partial => "account", :object => @buyer %>
+  #
+  #   <% for ad in @advertisements %>
+  #     <%= render :partial => "ad", :object => ad %>
+  #   <% end %>
+  # 
+  # The :object and :as options can be used together. We might have a partial which we have named genericly,
+  # such as 'form'. Using :object and :as together helps us.
+  # 
+  #   <%= render :partial => "form", :object => @contract, :as => :contract %>
   # == Rendering a collection of partials
   #
   # The example of partial use describes a familiar pattern where a template needs to iterate over an array and
@@ -39,6 +69,8 @@ module ActionView
   # iteration counter will automatically be made available to the template with a name of the form
   # +partial_name_counter+. In the case of the example above, the template would be fed +ad_counter+.
   #
+  # The :as option may be used when rendering partials.
+  # 
   # NOTE: Due to backwards compatibility concerns, the collection can't be one of hashes. Normally you'd also
   # just keep domain objects, like Active Records, in there.
   #