Added partial layouts (see example in action_view/lib/partials.rb) [DHH]

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7261 5ecf4fe2-1ee6-0310-87b1-e25e094e27de

1 files changed, 57 insertions, 0 deletions

diff --git a/actionpack/lib/action_view/partials.rb b/actionpack/lib/action_view/partials.rb
index 9da33d2ac8..e26ca499d0 100644
--- a/actionpack/lib/action_view/partials.rb
+++ b/actionpack/lib/action_view/partials.rb
@@ -44,6 +44,63 @@ module ActionView
   #   <%= render :partial => "advertisement/ad", :locals => { :ad => @advertisement } %>
   #
   # This will render the partial "advertisement/_ad.erb" regardless of which controller this is being called from.
+  #
+  # == Rendering partials with layouts
+  #
+  # Partials can have their own layouts applied to them. These layouts are different than the ones that are specified globally
+  # for the entire action, but they work in a similar fashion. Imagine a list with two types of users:
+  #
+  #   <!-- app/views/users/index.html.erb -->
+  #   Here's the administrator:
+  #   <%= render :partial => "user", :layout => "administrator", :locals => { :user => administrator } %>
+  #
+  #   Here's the editor:
+  #   <%= render :partial => "user", :layout => "editor", :locals => { :user => editor } %>
+  #
+  #   <!-- app/views/users/_user.html.erb -->
+  #   Name: <%= user.name %>
+  #
+  #   <!-- app/views/users/_administrator.html.erb -->
+  #   <div id="administrator">
+  #     Budget: $<%= user.budget %>
+  #     <%= yield %>
+  #   </div>
+  #
+  #   <!-- app/views/users/_editor.html.erb -->
+  #   <div id="editor">
+  #     Deadline: $<%= user.deadline %>
+  #     <%= yield %>
+  #   </div>
+  #
+  # ...this will return:
+  #
+  #   Here's the administrator:
+  #   <div id="administrator">
+  #     Budget: $<%= user.budget %>
+  #     Name: <%= user.name %>
+  #   </div>
+  #
+  #   Here's the editor:
+  #   <div id="editor">
+  #     Deadline: $<%= user.deadline %>
+  #     Name: <%= user.name %>
+  #   </div>
+  #
+  # You can also apply a layout to a block within any template:
+  #
+  #   <!-- app/views/users/_chief.html.erb -->
+  #   <% render(:layout => "administrator", :locals => { :user => chief }) do %>
+  #     Title: <%= chief.title %>
+  #   <% end %>
+  #
+  # ...this will return:
+  #
+  #   <div id="administrator">
+  #     Budget: $<%= user.budget %>
+  #     Title: <%= chief.name %>
+  #   </div>
+  #
+  # As you can see, the :locals hash is shared between both the partial and its layout.
   module Partials
     private
       # Deprecated, use render :partial