Ruby on Rails | Screencasts | Download | Documentation | Weblog | Community | Source

Changeset 7148

Show
Ignore:
Timestamp:
06/28/07 18:32:34 (1 year ago)
Author:
bitsweat
Message:

Improve capture helper documentation. Closes #8796.

Files:

Legend:

Unmodified
Added
Removed
Modified
Copied
Moved

  • trunk/actionpack/CHANGELOG

    r7138 r7148  
    11*SVN* 
     2 
     3* Improve capture helper documentation.  #8796 [kampers] 
    24 
    35* Prefix nested resource named routes with their action name, e.g. new_group_user_path(@group) instead of group_new_user_path(@group). The old nested action named route is deprecated in Rails 1.2.4.  #8558 [David Chelimsky] 

  • trunk/actionpack/lib/action_view/helpers/capture_helper.rb

    r7106 r7148  
    44    # can be used in other parts of a template or layout file. 
    55    # It provides a method to capture blocks into variables through capture and  
    6     # a way to capture a block of code for use in a layout through content_for. 
     6    # a way to capture a block of markup for use in a layout through content_for. 
    77    module CaptureHelper 
    8       # The capture method allows you to extract a part of the template into a  
    9       # variable. You can then use this value anywhere in your templates or layout.  
     8      # The capture method allows you to extract part of a template into a  
     9      # variable. You can then use this variable anywhere in your templates or layout.  
    1010      #  
    1111      # ==== Examples 
    …… 
    2323      #   end 
    2424      # 
    25       # You can then use the content as a variable anywhere else.  For 
    26       # example: 
     25      # You can then use that variable anywhere else.  For example: 
    2726      # 
    2827      #   <html> 
    …… 
    4746      end 
    4847       
    49       # Calling content_for stores the block of markup in an identifier for later use. 
    50       # You can make subsequent calls to the stored content in another template or in the layout 
    51       # by calling it by name with <tt>yield</tt>. 
     48      # Calling content_for stores a block of markup in an identifier for later use. 
     49      # You can make subsequent calls to the stored content in other templates or the layout 
     50      # by passing the identifier as an argument to <tt>yield</tt>. 
    5251      #  
    5352      # ==== Examples 
    5453      #  
    55       #   <% content_for("authorized") do %> 
    56       #     alert('You are not authorized for that!') 
     54      #   <% content_for :not_authorized do %> 
     55      #     alert('You are not authorized to do that!') 
    5756      #   <% end %> 
    5857      # 
    59       # You can then use <tt>yield :authorized</tt> anywhere in your templates. 
     58      # You can then use <tt>yield :not_authorized</tt> anywhere in your templates. 
    6059      # 
    61       #   <%= yield :authorized if current_user == nil %> 
     60      #   <%= yield :not_authorized if current_user.nil? %> 
    6261      # 
    63       # You can also use these variables in a layout.  For example: 
     62      # You can also use this syntax alongside an existing call to <tt>yield</tt> in a layout.  For example: 
    6463      # 
    6564      #   <!-- This is the layout --> 
    …… 
    7473      #   </html> 
    7574      # 
    76       # And now we'll create a view that has a content_for call that 
     75      # And now, we'll create a view that has a content_for call that 
    7776      # creates the <tt>script</tt> identifier. 
    7877      # 
    …… 
    8079      #   Please login! 
    8180      # 
    82       #   <% content_for("script") do %> 
    83       #     <script type="text/javascript">alert('You are not authorized for this action!')</script> 
     81      #   <% content_for :script do %> 
     82      #     <script type="text/javascript">alert('You are not authorized to view this page!')</script> 
    8483      #   <% end %> 
    8584      # 
    86       # Then in another view you may want to do something like this: 
     85      # Then, in another view, you could to do something like this: 
    8786      # 
    8887      #   <%= link_to_remote 'Logout', :action => 'logout' %> 
    8988      # 
    90       #   <% content_for("script") do %> 
     89      #   <% content_for :script do %> 
    9190      #     <%= javascript_include_tag :defaults %> 
    9291      #   <% end %> 
    9392      # 
    94       # That will include Prototype and Scriptaculous into the page; this technique 
    95       # is useful if you'll only be using these scripts on a few views. 
     93      # That will place <script> tags for Prototype, Scriptaculous, and application.js (if it exists) 
     94      # on the page; this technique is useful if you'll only be using these scripts in a few views. 
    9695      # 
    97       # NOTE: Beware that content_for is ignored in caches. So you shouldn't use it 
    98       # for elements that are going to be fragment cached. 
     96      # Also, note that content_for concatenates the blocks it is given for a particular 
     97      # identifier in order. For example: 
    9998      # 
    100       # The deprecated way of accessing a content_for block was to use a instance variable 
    101       # named @@content_for_#{name_of_the_content_block}@. So <tt><%= content_for('footer') %></tt> 
    102       # would be avaiable as <tt><%= @content_for_footer %></tt>. The preferred notation now is 
     99      #   <% content_for :navigation do %> 
     100      #     <li><%= link_to 'Home', :action => 'index' %></li> 
     101      #   <% end %> 
     102      # 
     103      #   <!-- Add some other content, or use a different template: --> 
     104      #  
     105      #   <% content_for :navigation do %> 
     106      #     <li><%= link_to 'Login', :action => 'login' %></li> 
     107      #   <% end %> 
     108      # 
     109      # Then, in another template or layout, this code would render both links in order: 
     110      # 
     111      #   <ul><%= yield :navigation %></ul> 
     112      #       
     113      # WARNING: content_for is ignored in caches. So you shouldn't use it 
     114      # for elements that will be fragment cached. 
     115      # 
     116      # The deprecated way of accessing a content_for block is to use an instance variable 
     117      # named <tt>@content_for_#{name_of_the_content_block}</tt>. So <tt><%= content_for :footer %></tt> 
     118      # would be avaiable as <tt><%= @content_for_footer %></tt>. The preferred usage is now 
    103119      # <tt><%= yield :footer %></tt>. 
    104120      def content_for(name, content = nil, &block)