diff --git a/railties/guides/source/action_view_overview.textile b/railties/guides/source/action_view_overview.textile index 1a81920249..ab9b910270 100644 --- a/railties/guides/source/action_view_overview.textile +++ b/railties/guides/source/action_view_overview.textile @@ -20,7 +20,28 @@ Note: Some features of Action View are tied to Active Record, but that doesn't m h3. Using Action View with Rails -TODO... +For each controller there is an associated directory in the app/views directory which holds the template files that make up the views associated with that controller. These files are used to display the view that results from each controller action. + +Let's take a look at what Rails does by default when creating a new resource using the scaffold generator: + + +$ rails generate scaffold post + [...] + invoke scaffold_controller + create app/controllers/posts_controller.rb + invoke erb + create app/views/posts + create app/views/posts/index.html.erb + create app/views/posts/edit.html.erb + create app/views/posts/show.html.erb + create app/views/posts/new.html.erb + create app/views/posts/_form.html.erb + [...] + + +There is a naming convention for views in Rails. Typically, the views share their name with the associated controller action, as you can see above. +For example, the index controller action of the posts_controller.rb will use the index.html.erb view file in the app/views/posts directory. +The complete HTML returned to the client is composed of a combination of this ERB file, a layout template that wraps it, and all the partials that the view may reference. Later on this guide you can find a more detailed documentation of each one of this three components. h3. Using Action View outside of Rails @@ -94,9 +115,112 @@ 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. -TODO see http://guides.rubyonrails.org/layouts_and_rendering.html +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: + + +<%= render "menu" %> + + +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: + + +<%= render "shared/menu" %> + + +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: + + +<%= render "shared/ad_banner" %> + +

Products

+ +

Here are a few of our fine products:

+<% @products.each do |product| %> + <%= render :partial => "product", :locals => { :product => product } %> +<% end %> + +<%= render "shared/footer" %> + + +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 ActionView::Partials::PartialRenderer has its object in a local variable with the same name as the template. So, given + + +<%= render :partial => "product" %> + + +within product we'll get @product in the local variable +product+, as if we had written: + + +<%= render :partial => "product", :locals => { :product => @product } %> + + +With the :as 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: + + +<%= render :partial => "product", :as => 'item' %> + + +The :object 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: + + +<%= render :partial => "product", :locals => { :product => @item } %> + + +you'd do: + + +<%= render :partial => "product", :object => @item %> + + +The :object and :as 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: + + +<%= render :partial => "product", :collection => @products %> + + +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: + + +<%= render @products %> + + +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. + +h5. Spacer Templates + +You can also specify a second partial to be rendered between instances of the main partial by using the +:spacer_template+ option: + + +<%= render @products, :spacer_template => "product_ruler" %> + + +Rails will render the +_product_ruler+ partial (with no data passed in to it) between each pair of +_product+ partials. h3. Using Templates, Partials and Layouts in "The Rails Way"