vendor/rails/actionpack/lib/action_view/helpers/capture_helper.rb

   1 module ActionView
   2   module Helpers
   3     # CaptureHelper exposes methods to let you extract generated markup which
   4     # can be used in other parts of a template or layout file.
   5     # It provides a method to capture blocks into variables through capture and
   6     # a way to capture a block of markup for use in a layout through content_for.
   7     module CaptureHelper
   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.
  10       #
  11       # ==== Examples
  12       # The capture method can be used in ERb templates...
  13       #
  14       #   <% @greeting = capture do %>
  15       #     Welcome to my shiny new web page!  The date and time is
  16       #     <%= Time.now %>
  17       #   <% end %>
  18       #
  19       # ...and Builder (RXML) templates.
  20       #
  21       #   @timestamp = capture do
  22       #     "The current timestamp is #{Time.now}."
  23       #   end
  24       #
  25       # You can then use that variable anywhere else.  For example:
  26       #
  27       #   <html>
  28       #   <head><title><%= @greeting %></title></head>
  29       #   <body>
  30       #   <b><%= @greeting %></b>
  31       #   </body></html>
  32       #
  33       def capture(*args, &block)
  34         # Return captured buffer in erb.
  35         if block_called_from_erb?(block)
  36           with_output_buffer { block.call(*args) }
  37         else
  38           # Return block result otherwise, but protect buffer also.
  39           with_output_buffer { return block.call(*args) }
  40         end
  41       end
  42
  43       # Calling content_for stores a block of markup in an identifier for later use.
  44       # You can make subsequent calls to the stored content in other templates or the layout
  45       # by passing the identifier as an argument to <tt>yield</tt>.
  46       #
  47       # ==== Examples
  48       #
  49       #   <% content_for :not_authorized do %>
  50       #     alert('You are not authorized to do that!')
  51       #   <% end %>
  52       #
  53       # You can then use <tt>yield :not_authorized</tt> anywhere in your templates.
  54       #
  55       #   <%= yield :not_authorized if current_user.nil? %>
  56       #
  57       # You can also use this syntax alongside an existing call to <tt>yield</tt> in a layout.  For example:
  58       #
  59       #   <%# This is the layout %>
  60       #   <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  61       #   <head>
  62       #     <title>My Website</title>
  63       #     <%= yield :script %>
  64       #   </head>
  65       #   <body>
  66       #     <%= yield %>
  67       #   </body>
  68       #   </html>
  69       #
  70       # And now, we'll create a view that has a content_for call that
  71       # creates the <tt>script</tt> identifier.
  72       #
  73       #   <%# This is our view %>
  74       #   Please login!
  75       #
  76       #   <% content_for :script do %>
  77       #     <script type="text/javascript">alert('You are not authorized to view this page!')</script>
  78       #   <% end %>
  79       #
  80       # Then, in another view, you could to do something like this:
  81       #
  82       #   <%= link_to_remote 'Logout', :action => 'logout' %>
  83       #
  84       #   <% content_for :script do %>
  85       #     <%= javascript_include_tag :defaults %>
  86       #   <% end %>
  87       #
  88       # That will place <script> tags for Prototype, Scriptaculous, and application.js (if it exists)
  89       # on the page; this technique is useful if you'll only be using these scripts in a few views.
  90       #
  91       # Note that content_for concatenates the blocks it is given for a particular
  92       # identifier in order. For example:
  93       #
  94       #   <% content_for :navigation do %>
  95       #     <li><%= link_to 'Home', :action => 'index' %></li>
  96       #   <% end %>
  97       #
  98       #   <%#  Add some other content, or use a different template: %>
  99       #
 100       #   <% content_for :navigation do %>
 101       #     <li><%= link_to 'Login', :action => 'login' %></li>
 102       #   <% end %>
 103       #
 104       # Then, in another template or layout, this code would render both links in order:
 105       #
 106       #   <ul><%= yield :navigation %></ul>
 107       #
 108       # Lastly, simple content can be passed as a parameter:
 109       #
 110       #   <% content_for :script, javascript_include_tag(:defaults) %>
 111       #
 112       # WARNING: content_for is ignored in caches. So you shouldn't use it
 113       # for elements that will be fragment cached.
 114       #
 115       # The deprecated way of accessing a content_for block is to use an instance variable
 116       # named <tt>@content_for_#{name_of_the_content_block}</tt>. The preferred usage is now
 117       # <tt><%= yield :footer %></tt>.
 118       def content_for(name, content = nil, &block)
 119         ivar = "@content_for_#{name}"
 120         content = capture(&block) if block_given?
 121         instance_variable_set(ivar, "#{instance_variable_get(ivar)}#{content}")
 122         nil
 123       end
 124
 125       # Use an alternate output buffer for the duration of the block.
 126       # Defaults to a new empty string.
 127       def with_output_buffer(buf = '') #:nodoc:
 128         self.output_buffer, old_buffer = buf, output_buffer
 129         yield
 130         output_buffer
 131       ensure
 132         self.output_buffer = old_buffer
 133       end
 134     end
 135   end
 136 end