From 7bb20659c295d2b6a2820295b948ae3a2c0fa99e Mon Sep 17 00:00:00 2001
From: Marcel Molina <marcel@vernix.org>
Date: Tue, 25 Apr 2006 04:03:51 +0000
Subject: Update layout and content_for documentation to use yield rather than
 magic @content_for instance variables.

git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@4262 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
---
 actionpack/lib/action_controller/layout.rb         | 12 ++++----
 .../templates/scaffolds/layout.rhtml               |  2 +-
 .../lib/action_view/helpers/capture_helper.rb      | 32 ++++++++++++----------
 3 files changed, 25 insertions(+), 21 deletions(-)

(limited to 'actionpack/lib')

diff --git a/actionpack/lib/action_controller/layout.rb b/actionpack/lib/action_controller/layout.rb
index 7ecff73380..4e9e42d468 100644
--- a/actionpack/lib/action_controller/layout.rb
+++ b/actionpack/lib/action_controller/layout.rb
@@ -27,7 +27,7 @@ module ActionController #:nodoc:
     # that the header and footer are only mentioned in one place, like this:
     #
     #   <!-- The header part of this layout -->
-    #   <%= @content_for_layout %>
+    #   <%= yield %>
     #   <!-- The footer part of this layout -->
     #
     # And then you have content pages that look like this:
@@ -47,7 +47,7 @@ module ActionController #:nodoc:
     # references that won't materialize before rendering time:
     #
     #   <h1><%= @page_title %></h1>
-    #   <%= @content_for_layout %>
+    #   <%= yield %>
     #
     # ...and content pages that fulfill these references _at_ rendering time:
     #
@@ -159,10 +159,12 @@ module ActionController #:nodoc:
     #
     # As you can see, you pass the template as the first parameter, the status code as the second ("200" is OK), and the layout
     # as the third.
+    #
+    # NOTE: The old notation for rendering the view from a layout was to expose the magic <tt>@content_for_layout</tt> instance 
+    # variable. The preferred notation now is to use <tt>yield</tt>, as documented above.
     module ClassMethods
-      # If a layout is specified, all actions rendered through render and render_action will have their result assigned 
-      # to <tt>@content_for_layout</tt>, which can then be used by the layout to insert their contents with
-      # <tt><%= @content_for_layout %></tt>. This layout can itself depend on instance variables assigned during action
+      # If a layout is specified, all rendered actions will have their result rendered  
+      # when the layout<tt>yield</tt>'s. This layout can itself depend on instance variables assigned during action
       # performance and have access to them as any normal template would.
       def layout(template_name, conditions = {})
         add_layout_conditions(conditions)
diff --git a/actionpack/lib/action_controller/templates/scaffolds/layout.rhtml b/actionpack/lib/action_controller/templates/scaffolds/layout.rhtml
index 120f0cfb62..759781e0e7 100644
--- a/actionpack/lib/action_controller/templates/scaffolds/layout.rhtml
+++ b/actionpack/lib/action_controller/templates/scaffolds/layout.rhtml
@@ -63,7 +63,7 @@
 
 <p style="color: green"><%= flash[:notice] %></p>
 
-<%= @content_for_layout %>
+<%= yield %>
 
 </body>
 </html>
diff --git a/actionpack/lib/action_view/helpers/capture_helper.rb b/actionpack/lib/action_view/helpers/capture_helper.rb
index 9828fe0fa2..8dadf21865 100644
--- a/actionpack/lib/action_view/helpers/capture_helper.rb
+++ b/actionpack/lib/action_view/helpers/capture_helper.rb
@@ -1,6 +1,6 @@
 module ActionView
   module Helpers
-    # Capture lets you extract parts of code into instance variables which
+    # Capture lets you extract parts of code which
     # can be used in other points of the template or even layout file.
     #
     # == Capturing a block into an instance variable
@@ -8,12 +8,11 @@ module ActionView
     #   <% @script = capture do %>
     #     [some html...]
     #   <% end %>
-    #  
     #
     # == Add javascript to header using content_for
     #
-    # content_for("name") is a wrapper for capture which will store the 
-    # fragment in a instance variable similar to @content_for_layout.
+    # content_for("name") is a wrapper for capture which will 
+    # make the fragment available by name to a yielding layout or template.
     #
     # layout.rhtml:
     #
@@ -21,11 +20,11 @@ module ActionView
     #   <head>
     #	    <title>layout with js</title>
     #	    <script type="text/javascript">
-    #	    <%= @content_for_script %>
+    #	    <%= yield :script %>
     #   	</script>
     #   </head>
     #   <body>
-    #     <%= @content_for_layout %>
+    #     <%= yield %>
     #   </body>
     #   </html>
     #
@@ -69,13 +68,9 @@ module ActionView
         end
       end
       
-      # Content_for will store the given block
-      # in an instance variable for later use in another template
-      # or in the layout. 
-      # 
-      # The name of the instance variable is content_for_<name> 
-      # to stay consistent with @content_for_layout which is used 
-      # by ActionView's layouts
+      # Calling content_for stores the block of markup for later use.
+      # Subsequently, you can make calls to it by name with <tt>yield</tt>
+      # in another template or in the layout. 
       # 
       # Example:
       # 
@@ -83,10 +78,17 @@ module ActionView
       #     alert('hello world')
       #   <% end %>
       #
-      # You can use @content_for_header anywhere in your templates.
+      # You can use yield :header anywhere in your templates.
+      #
+      #   <%= yield :header %>
       #
       # NOTE: Beware that content_for is ignored in caches. So you shouldn't use it
-      # for elements that are going to be fragment cached. 
+      # for elements that are going to be fragment cached.
+      #
+      # The deprecated way of accessing a content_for block was to use a instance variable
+      # named @content_for_#{name_of_the_content_block}. So <tt><% content_for('footer') %></tt>
+      # would be avaiable as <tt><%= @content_for_footer %></tt>. The preferred notation now is
+      # <tt><%= yield :footer %></tt>.
       def content_for(name, &block)
         eval "@content_for_#{name} = (@content_for_#{name} || '') + capture(&block)"
       end
-- 
cgit v1.2.3