Ticket #7970: partials_docs.diff

actionpack/lib/action_view/partials.rb

@@ -1 +1 @@
-module ActionView
-There's also a convenience method for rendering sub templates within the current controller that depends on a single object
-(we call this kind of sub templates for partials). It relies on the fact that partials should follow the naming convention of being
-prefixed with an underscore -- as to separate them from regular templates that could be rendered on their own
+Partials are subtemplates that are rendered within the current controller that depend on a single object that is passed in as an
+instance variable. Partials differ from normal subtemplates in that they don't have access to the parent template's environment or 
+variables (but you can pass variables in)
-  #
-
+
+
+
+
+
-  #
+  # To separate them from regular templates that could be rendered on their own, partials should follow the naming convention of being 
+  # prefixed with an underscore (_).  So, for example, you would have "_login.erb" rather than "login.erb".  This naming doesn't affect 
+  # how they're called in code though, so when rendering a partial, only the name is required, not the underscore.
+  #
+  # For example, in a template for Advertiser#view_info (advertiser/view_info.erb), you may want to render the advertiser's account
+  # information through a partial.  To do so, you could do something like the following.
+  #
-  #  <%= render :partial => "account" %>
-  #
-  # This would render "advertiser/_account.erb" and pass the instance variable @account in as a local variable +account+ to
-
+
+
-  #
-
+
+
+
-  #
+  # === Passing in other local variables
+  # In addition to the partial-named instance variable, you can also provide a hash of values to be used as local variables in the partial.
+  # In another part of our advertisement application, in a template for Advertiser#buy, we could have:
+  #
-  #   <%= render :partial => "account", :locals => { :account => @buyer } %>
-  #
-  #   <% for ad in @advertisements %>
@@ -19 +37 @@
-  #   <% end %>
-  #
-  # This would first render "advertiser/_account.erb" with @buyer passed in as the local variable +account+, then render
-
+
+
-  #
+  #   <%= render :partial => "account_info", :locals => { :project => get_project(3), :user => current_user }
+  #
+  # The above code would pass in <tt>project</tt>, <tt>user</tt>, and the instance variable <tt>account_info</tt> as locals.
+  #
+  # === Sharing partials
+  # Like other templates and subtemplates, two or more controllers can share a set of partials. Rendering them is similar to other
+  # template types, and looks something like this:
+  #
+  #   <%= render :partial => "advertisement/ad", :locals => { :ad => @advertisement } %>
+  #
+  # This will render the partial "advertisement/_ad.erb" regardless of which controller this is being called from.
+  #
-  # == Rendering a collection of partials
-  #
-The example of partial use describes a familiar pattern where
-T
-So the three-lined example in "Using partials" can be rewritten
-with a single line:
+A familiar pattern for using partials is when
+As a response, t
+ So, rather than using a for loop or some similar construction to iterate
+over elements, rending a partial for each one, you can use the <tt>collection</tt> parameter for the <tt>render</tt> method.
-  #
-  #   <%= render :partial => "ad", :collection => @advertisements %>
-  #
-  # This will render "advertiser/_ad.erb" and pass the local variable +ad+ to the template for display. An iteration counter
-. In the case of th
-example above, the template would be fed +ad_counter+
+ (for example, the above exampl
+template would be fed +ad_counter+), you can use that to indicate counts and so on
-  #
-
-
+
-  #
-  # == Rendering shared partials
-  #
-  # Two controllers can share a set of partials and render them like this:
-  #
-  #   <%= render :partial => "advertisement/ad", :locals => { :ad => @advertisement } %>
-  #
-  # This will render the partial "advertisement/_ad.erb" regardless of which controller this is being called from.
-  module Partials
-    private
-      # Deprecated, use render :partial