Add changelog entry and some docs for collection + layout

actionpack/CHANGELOG.md

@@ -1,5 +1,8 @@
 ## Rails 4.0.0 (unreleased) ##
 
+*   Make current object and counter (when it applies) variables accessible when
+    rendering templates with :object / :collection. *Carlos Antonio da Silva*
+
 *   JSONP now uses mimetype application/javascript instead of application/json *omjokine*
 
 *   Allow to lazy load `default_form_builder` by passing a `String` instead of a constant. *Piotr Sarnacki*

actionpack/lib/action_view/renderer/partial_renderer.rb

@@ -158,8 +158,8 @@ module ActionView
   #     Name: <%= user.name %>
   #   </div>
   #
-  # If a collection is given, the layout will be rendered once for each item in the collection. Just think
-  # these two snippets have the same output:
+  # If a collection is given, the layout will be rendered once for each item in
+  # the collection. Just think these two snippets have the same output:
   #
   #   <%# app/views/users/_user.html.erb %>
   #   Name: <%= user.name %>
@@ -184,7 +184,7 @@ module ActionView
   #     <%= render :partial => "user", :layout => "li_layout", :collection => users %>
   #   </ul>
   #
-  #   Given two users whose names are Alice and Bob, these snippets return:
+  # Given two users whose names are Alice and Bob, these snippets return:
   #
   #   <ul>
   #     <li>
@@ -195,6 +195,10 @@ module ActionView
   #     </li>
   #   </ul>
   #
+  # The current object being rendered, as well as the object_counter, will be
+  # available as local variables inside the layout template under the same names
+  # as available in the partial.
+  #
   # You can also apply a layout to a block within any template:
   #
   #   <%# app/views/users/_chief.html.erb &>

guides/source/layouts_and_rendering.textile

@@ -1193,6 +1193,16 @@ h5. Spacer Templates
 
 Rails will render the +_product_ruler+ partial (with no data passed in to it) between each pair of +_product+ partials.
 
+h5. Partial Layouts
+
+When rendering collections it is also possible to use the +:layout+ option:
+
+<erb>
+<%= render :partial => "product", :collection => @products, :layout => "special_layout" %>
+</erb>
+
+The layout will be rendered together with the partial for each item in the collection. The current object and object_counter variables will be available in the layout as well, the same way they do within the partial.
+
 h4. Using Nested Layouts
 
 You may find that your application requires a layout that differs slightly from your regular application layout to support one particular controller. Rather than repeating the main layout and editing it, you can accomplish this by using nested layouts (sometimes called sub-templates). Here's an example: