diff options
author | Sebastian Martinez <sebastian@wyeworks.com> | 2011-04-16 17:14:46 -0300 |
---|---|---|
committer | Sebastian Martinez <sebastian@wyeworks.com> | 2011-04-16 17:14:46 -0300 |
commit | eecb8385b4901f6c4e9679a5fc9f065a639f9ac7 (patch) | |
tree | 3a626ec751899a06e06cab3101c4fc9ef6881026 /railties/guides/source/action_view_overview.textile | |
parent | 7c9927a4092f18c449538c6656f66ef6c47205f2 (diff) | |
download | rails-eecb8385b4901f6c4e9679a5fc9f065a639f9ac7.tar.gz rails-eecb8385b4901f6c4e9679a5fc9f065a639f9ac7.tar.bz2 rails-eecb8385b4901f6c4e9679a5fc9f065a639f9ac7.zip |
Added Partials section to ActionView guide.
Diffstat (limited to 'railties/guides/source/action_view_overview.textile')
-rw-r--r-- | railties/guides/source/action_view_overview.textile | 97 |
1 files changed, 95 insertions, 2 deletions
diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index 33735b7944..72fcb8c0e6 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -115,9 +115,102 @@ TODO needs a screenshot? I have one - not sure where to put it. h3. Templates, Partials and Layouts -TODO... +As mentioned before, the final HTML output is a composition of three Rails elements: +Templates+, +Partials+ and +Layouts+. +Find below a brief overview of each one of them. + +h4. Partials + +Partial templates – usually just called "partials" – are another device for breaking the rendering process into more manageable chunks. With a partial, you can move the code for rendering a particular piece of a response to its own file. + +h5. Naming Partials + +To render a partial as part of a view, you use the +render+ method within the view: + +<ruby> +<%= render "menu" %> +</ruby> + +This will render a file named +_menu.html.erb+ at that point within the view is being rendered. Note the leading underscore character: partials are named with a leading underscore to distinguish them from regular views, even though they are referred to without the underscore. This holds true even when you're pulling in a partial from another folder: + +<ruby> +<%= render "shared/menu" %> +</ruby> + +That code will pull in the partial from +app/views/shared/_menu.html.erb+. + +h5. Using Partials to Simplify Views + +One way to use partials is to treat them as the equivalent of subroutines: as a way to move details out of a view so that you can grasp what's going on more easily. For example, you might have a view that looked like this: + +<erb> +<%= render "shared/ad_banner" %> + +<h1>Products</h1> + +<p>Here are a few of our fine products:</p> +<% @products.each do |product| %> + <%= render :partial => "product", :locals => { :product => product } %> +<% end %> + +<%= render "shared/footer" %> +</erb> + +Here, the +_ad_banner.html.erb+ and +_footer.html.erb+ partials could contain content that is shared among many pages in your application. You don't need to see the details of these sections when you're concentrating on a particular page. + +h5. The :as and :object options + +By default <tt>ActionView::Partials::PartialRenderer</tt> has its object in a local variable with the same name as the template. So, given + +<erb> +<%= render :partial => "product" %> +</erb> + +within product we'll get <tt>@product</tt> in the local variable +product+, as if we had written: + +<erb> +<%= render :partial => "product", :locals => { :product => @product } %> +</erb> + +With the <tt>:as</tt> option we can specify a different name for said local variable. For example, if we wanted it to be +item+ instead of product+ we'd do: + +<erb> +<%= render :partial => "product", :as => 'item' %> +</erb> + +The <tt>:object</tt> option can be used to directly specify which object is rendered into the partial; useful when the template's object is elsewhere, in a different ivar or in a local variable for instance. + +For example, instead of: + +<erb> +<%= render :partial => "product", :locals => { :product => @item } %> +</erb> + +you'd do: + +<erb> +<%= render :partial => "product", :object => @item %> +</erb> + +The <tt>:object</tt> and <tt>:as</tt> options can be used together. + +h5. Rendering Collections + +The example of partial use describes a familiar pattern where a template needs to iterate over an array and render a sub template for each of the elements. This pattern has been implemented as a single method that accepts an array and renders a partial by the same name as the elements contained within. +So the three-lined example for rendering all the products can be rewritten with a single line: + +<erb> +<%= render :partial => "product", :collection => @products %> +</erb> + +When a partial is called with a pluralized collection, then the individual instances of the partial have access to the member of the collection being rendered via a variable named after the partial. In this case, the partial is +_product+ , and within the +_product+ partial, you can refer to +product+ to get the instance that is being rendered. + +You can use a shorthand syntax for rendering collections. Assuming @products is a collection of +Product+ instances, you can simply write the following to produce the same result: + +<erb> +<%= render @products %> +</erb> -TODO see http://guides.rubyonrails.org/layouts_and_rendering.html +Rails determines the name of the partial to use by looking at the model name in the collection. In fact, you can even create a heterogeneous collection and render it this way, and Rails will choose the proper partial for each member of the collection. h3. Using Templates, Partials and Layouts in "The Rails Way" |