diff options
| author | Jeremy Kemper <jeremy@bitsweat.net> | 2007-06-28 18:32:34 +0000 |
|---|---|---|
| committer | Jeremy Kemper <jeremy@bitsweat.net> | 2007-06-28 18:32:34 +0000 |
| commit | dfc15e122afcc7e3cfabaadfbac639af7e846b5a (patch) | |
| tree | a452750e7855d137531e81b7ca523f8e40213891 | |
| parent | f26141c98deed64009b95190e25700eecdfdc403 (diff) | |
| download | rails-dfc15e122afcc7e3cfabaadfbac639af7e846b5a.tar.gz rails-dfc15e122afcc7e3cfabaadfbac639af7e846b5a.tar.bz2 rails-dfc15e122afcc7e3cfabaadfbac639af7e846b5a.zip | |
Improve capture helper documentation. Closes #8796.
git-svn-id: http://svn-commit.rubyonrails.org/rails/trunk@7148 5ecf4fe2-1ee6-0310-87b1-e25e094e27de
| -rw-r--r-- | actionpack/CHANGELOG | 2 | ||||
| -rw-r--r-- | actionpack/lib/action_view/helpers/capture_helper.rb | 66 |
2 files changed, 43 insertions, 25 deletions
diff --git a/actionpack/CHANGELOG b/actionpack/CHANGELOG index 6fb3acc1f2..c5953703a7 100644 --- a/actionpack/CHANGELOG +++ b/actionpack/CHANGELOG @@ -1,5 +1,7 @@ *SVN* +* Improve capture helper documentation. #8796 [kampers] + * 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] * Allow sweepers to be created solely for expiring after controller actions, not model changes [DHH] diff --git a/actionpack/lib/action_view/helpers/capture_helper.rb b/actionpack/lib/action_view/helpers/capture_helper.rb index 7cf2b02659..14bc8efee2 100644 --- a/actionpack/lib/action_view/helpers/capture_helper.rb +++ b/actionpack/lib/action_view/helpers/capture_helper.rb @@ -3,10 +3,10 @@ module ActionView # CaptureHelper exposes methods to let you extract generated markup which # can be used in other parts of a template or layout file. # It provides a method to capture blocks into variables through capture and - # a way to capture a block of code for use in a layout through content_for. + # a way to capture a block of markup for use in a layout through content_for. module CaptureHelper - # The capture method allows you to extract a part of the template into a - # variable. You can then use this value anywhere in your templates or layout. + # The capture method allows you to extract part of a template into a + # variable. You can then use this variable anywhere in your templates or layout. # # ==== Examples # The capture method can be used in RHTML (ERb) templates... @@ -22,8 +22,7 @@ module ActionView # "The current timestamp is #{Time.now}." # end # - # You can then use the content as a variable anywhere else. For - # example: + # You can then use that variable anywhere else. For example: # # <html> # <head><title><%= @greeting %></title></head> @@ -46,21 +45,21 @@ module ActionView end end - # Calling content_for stores the block of markup in an identifier for later use. - # You can make subsequent calls to the stored content in another template or in the layout - # by calling it by name with <tt>yield</tt>. + # Calling content_for stores a block of markup in an identifier for later use. + # You can make subsequent calls to the stored content in other templates or the layout + # by passing the identifier as an argument to <tt>yield</tt>. # # ==== Examples # - # <% content_for("authorized") do %> - # alert('You are not authorized for that!') + # <% content_for :not_authorized do %> + # alert('You are not authorized to do that!') # <% end %> # - # You can then use <tt>yield :authorized</tt> anywhere in your templates. + # You can then use <tt>yield :not_authorized</tt> anywhere in your templates. # - # <%= yield :authorized if current_user == nil %> + # <%= yield :not_authorized if current_user.nil? %> # - # You can also use these variables in a layout. For example: + # You can also use this syntax alongside an existing call to <tt>yield</tt> in a layout. For example: # # <!-- This is the layout --> # <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> @@ -73,33 +72,50 @@ module ActionView # </body> # </html> # - # And now we'll create a view that has a content_for call that + # And now, we'll create a view that has a content_for call that # creates the <tt>script</tt> identifier. # # <!-- This is our view --> # Please login! # - # <% content_for("script") do %> - # <script type="text/javascript">alert('You are not authorized for this action!')</script> + # <% content_for :script do %> + # <script type="text/javascript">alert('You are not authorized to view this page!')</script> # <% end %> # - # Then in another view you may want to do something like this: + # Then, in another view, you could to do something like this: # # <%= link_to_remote 'Logout', :action => 'logout' %> # - # <% content_for("script") do %> + # <% content_for :script do %> # <%= javascript_include_tag :defaults %> # <% end %> # - # That will include Prototype and Scriptaculous into the page; this technique - # is useful if you'll only be using these scripts on a few views. + # That will place <script> tags for Prototype, Scriptaculous, and application.js (if it exists) + # on the page; this technique is useful if you'll only be using these scripts in a few views. # - # NOTE: Beware that content_for is ignored in caches. So you shouldn't use it - # for elements that are going to be fragment cached. + # Also, note that content_for concatenates the blocks it is given for a particular + # identifier in order. For example: # - # 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 + # <% content_for :navigation do %> + # <li><%= link_to 'Home', :action => 'index' %></li> + # <% end %> + # + # <!-- Add some other content, or use a different template: --> + # + # <% content_for :navigation do %> + # <li><%= link_to 'Login', :action => 'login' %></li> + # <% end %> + # + # Then, in another template or layout, this code would render both links in order: + # + # <ul><%= yield :navigation %></ul> + # + # WARNING: content_for is ignored in caches. So you shouldn't use it + # for elements that will be fragment cached. + # + # The deprecated way of accessing a content_for block is to use an instance variable + # named <tt>@content_for_#{name_of_the_content_block}</tt>. So <tt><%= content_for :footer %></tt> + # would be avaiable as <tt><%= @content_for_footer %></tt>. The preferred usage is now # <tt><%= yield :footer %></tt>. def content_for(name, content = nil, &block) eval "@content_for_#{name} = (@content_for_#{name} || '') + capture(&block)" |