rails / rails

Ruby on Rails

This URL has Read+Write access

rails / actionpack / lib / action_view / partials.rb
raw normal view history
db045dbb » dhh 2004-11-23 Initial 1 module ActionView
2 # There's also a convenience method for rendering sub templates within the current controller that depends on a single object
3 # (we call this kind of sub templates for partials). It relies on the fact that partials should follow the naming convention of being
6ee06ebe » dhh 2005-04-16 Changed render_partial to t... 4 # prefixed with an underscore -- as to separate them from regular templates that could be rendered on their own.
5 #
6 # In a template for Advertiser#account:
7 #
8e56e090 » dhh 2005-06-21 Updated documentation for p... 8 # <%= render :partial => "account" %>
6ee06ebe » dhh 2005-04-16 Changed render_partial to t... 9 #
10 # This would render "advertiser/_account.rhtml" and pass the instance variable @account in as a local variable +account+ to
11 # the template for display.
12 #
13 # In another template for Advertiser#buy, we could have:
14 #
8e56e090 » dhh 2005-06-21 Updated documentation for p... 15 # <%= render :partial => "account", :locals => { :account => @buyer } %>
db045dbb » dhh 2004-11-23 Initial 16 #
17 # <% for ad in @advertisements %>
8e56e090 » dhh 2005-06-21 Updated documentation for p... 18 # <%= render :partial => "ad", :locals => { :ad => ad } %>
db045dbb » dhh 2004-11-23 Initial 19 # <% end %>
20 #
6ee06ebe » dhh 2005-04-16 Changed render_partial to t... 21 # This would first render "advertiser/_account.rhtml" with @buyer passed in as the local variable +account+, then render
22 # "advertiser/_ad.rhtml" and pass the local variable +ad+ to the template for display.
db045dbb » dhh 2004-11-23 Initial 23 #
24 # == Rendering a collection of partials
25 #
098fa943 » dhh 2005-02-07 Fixed documentation snafus ... 26 # The example of partial use describes a familiar pattern where a template needs to iterate over an array and render a sub
db045dbb » dhh 2004-11-23 Initial 27 # template for each of the elements. This pattern has been implemented as a single method that accepts an array and renders
28 # a partial by the same name as the elements contained within. So the three-lined example in "Using partials" can be rewritten
29 # with a single line:
30 #
8e56e090 » dhh 2005-06-21 Updated documentation for p... 31 # <%= render :partial => "ad", :collection => @advertisements %>
db045dbb » dhh 2004-11-23 Initial 32 #
33 # This will render "advertiser/_ad.rhtml" and pass the local variable +ad+ to the template for display. An iteration counter
34 # will automatically be made available to the template with a name of the form +partial_name_counter+. In the case of the
35 # example above, the template would be fed +ad_counter+.
703d18ea » dhh 2005-07-03 Added note about render_par... 36 #
37 # NOTE: Due to backwards compatibility concerns, the collection can't be one of hashes. Normally you'd also just keep domain objects,
38 # like Active Records, in there.
db045dbb » dhh 2004-11-23 Initial 39 #
40 # == Rendering shared partials
41 #
42 # Two controllers can share a set of partials and render them like this:
43 #
8e56e090 » dhh 2005-06-21 Updated documentation for p... 44 # <%= render :partial => "advertisement/ad", :locals => { :ad => @advertisement } %>
db045dbb » dhh 2004-11-23 Initial 45 #
46 # This will render the partial "advertisement/_ad.rhtml" regardless of which controller this is being called from.
47 module Partials
8e56e090 » dhh 2005-06-21 Updated documentation for p... 48 # Deprecated, use render :partial
4f40b2d8 » dhh 2005-07-24 Improved performance of tes... 49 def render_partial(partial_path, local_assigns = nil, deprecated_local_assigns = nil) #:nodoc:
db045dbb » dhh 2004-11-23 Initial 50 path, partial_name = partial_pieces(partial_path)
82456d93 » dhh 2005-04-16 Fixed partials handling 51 object = extracting_object(partial_name, local_assigns, deprecated_local_assigns)
52 local_assigns = extract_local_assigns(local_assigns, deprecated_local_assigns)
4f40b2d8 » dhh 2005-07-24 Improved performance of tes... 53 local_assigns = local_assigns ? local_assigns.clone : {}
82456d93 » dhh 2005-04-16 Fixed partials handling 54 add_counter_to_local_assigns!(partial_name, local_assigns)
0886bb39 » sstephenson 2005-10-10 Fixed that an instance vari... 55 add_object_to_local_assigns!(partial_name, local_assigns, object)
82456d93 » dhh 2005-04-16 Fixed partials handling 56
ede50559 » jeremy 2005-11-16 Avoid logging code if logge... 57 if logger
58 ActionController::Base.benchmark("Rendered #{path}/_#{partial_name}", Logger::DEBUG, false) do
59 render("#{path}/_#{partial_name}", local_assigns)
60 end
61 else
c69160a9 » dhh 2005-10-01 Better logging about partia... 62 render("#{path}/_#{partial_name}", local_assigns)
63 end
db045dbb » dhh 2004-11-23 Initial 64 end
65
8e56e090 » dhh 2005-06-21 Updated documentation for p... 66 # Deprecated, use render :partial, :collection
4f40b2d8 » dhh 2005-07-24 Improved performance of tes... 67 def render_partial_collection(partial_name, collection, partial_spacer_template = nil, local_assigns = nil) #:nodoc:
db045dbb » dhh 2004-11-23 Initial 68 collection_of_partials = Array.new
9ee94ab1 » dhh 2004-12-12 Added that render_partial w... 69 counter_name = partial_counter_name(partial_name)
4f40b2d8 » dhh 2005-07-24 Improved performance of tes... 70 local_assigns = local_assigns ? local_assigns.clone : {}
db045dbb » dhh 2004-11-23 Initial 71 collection.each_with_index do |element, counter|
4f40b2d8 » dhh 2005-07-24 Improved performance of tes... 72 local_assigns[counter_name] = counter
73 collection_of_partials.push(render_partial(partial_name, element, local_assigns))
db045dbb » dhh 2004-11-23 Initial 74 end
75
01af965a » jamis 2005-09-01 Make rendering an empty par... 76 return " " if collection_of_partials.empty?
51f9c931 » dhh 2005-05-13 Fixed that render_partial_c... 77
db045dbb » dhh 2004-11-23 Initial 78 if partial_spacer_template
79 spacer_path, spacer_name = partial_pieces(partial_spacer_template)
80 collection_of_partials.join(render("#{spacer_path}/_#{spacer_name}"))
81 else
51f9c931 » dhh 2005-05-13 Fixed that render_partial_c... 82 collection_of_partials.join
db045dbb » dhh 2004-11-23 Initial 83 end
84 end
85
7ece0e16 » dhh 2005-03-09 Added render_partial/render... 86 alias_method :render_collection_of_partials, :render_partial_collection
87
db045dbb » dhh 2004-11-23 Initial 88 private
89 def partial_pieces(partial_path)
90 if partial_path.include?('/')
91 return File.dirname(partial_path), File.basename(partial_path)
92 else
b1999be5 » dhh 2005-02-14 A hopefully more successful... 93 return controller.class.controller_path, partial_path
db045dbb » dhh 2004-11-23 Initial 94 end
95 end
9ee94ab1 » dhh 2004-12-12 Added that render_partial w... 96
97 def partial_counter_name(partial_name)
56407737 » seckar 2005-09-27 Streamline render process, ... 98 "#{partial_name.split('/').last}_counter".intern
9ee94ab1 » dhh 2004-12-12 Added that render_partial w... 99 end
82456d93 » dhh 2005-04-16 Fixed partials handling 100
101 def extracting_object(partial_name, local_assigns, deprecated_local_assigns)
102 if local_assigns.is_a?(Hash) || local_assigns.nil?
103 controller.instance_variable_get("@#{partial_name}")
104 else
105 # deprecated form where object could be passed in as second parameter
106 local_assigns
107 end
108 end
109
110 def extract_local_assigns(local_assigns, deprecated_local_assigns)
111 local_assigns.is_a?(Hash) ? local_assigns : deprecated_local_assigns
112 end
113
114 def add_counter_to_local_assigns!(partial_name, local_assigns)
115 counter_name = partial_counter_name(partial_name)
116 local_assigns[counter_name] = 1 unless local_assigns.has_key?(counter_name)
117 end
ede50559 » jeremy 2005-11-16 Avoid logging code if logge... 118
0886bb39 » sstephenson 2005-10-10 Fixed that an instance vari... 119 def add_object_to_local_assigns!(partial_name, local_assigns, object)
e9a4e4d8 » jeremy 2005-11-17 Inline a method used by ren... 120 local_assigns[partial_name.intern] ||=
121 if object.is_a?(ActionView::Base::ObjectWrapper)
122 object.value
123 else
124 object
125 end || controller.instance_variable_get("@#{partial_name}")
0886bb39 » sstephenson 2005-10-10 Fixed that an instance vari... 126 end
db045dbb » dhh 2004-11-23 Initial 127 end
128 end