Functional tests now work properly, bearing in mind whether a user is logged in or...
[depot.git] / 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