5 KiB
A Guide to Using Partials
This guide elaborates on the use and function of partials in Ruby on Rails. As your Rails application grows, your view templates can start to contain a lot of duplicate view code. To manage and reduce this complexity, you can by abstract view template code into partials. Partials are reusable snippets of eRB template code stored in separate files with an underscore ('_') prefix.
Partials can be located anywhere in the app/views directory. File extensions for partials work just like other template files, they bear an extension that denotes what kind of code they generate. For example, _animal.html.erb and _animal.xml.erb are valid filenames for partials.
Partials can be inserted in eRB template code by calling the render method with the :partial option. For example:
<%= render :partial => 'foo' %>
This inserts the result of evaluating the template _foo.html.erb into the parent template file at this location. Note that render assumes that the partial will be in the same directory as the calling parent template and have the same file extension. Partials can be located anywhere within the app/views directory. To use a partial located in a different directory then it the parent, add a '/' before it:
<%= render :partial => '/common/foo' %>
Loads the partial file from the app/views/common/_foo.html.erb directory.
Abstracting views into partials can be approached in a number of different ways, depending on the situation. Sometimes, the code that you are abstracting is a specialized view of an object or a collection of objects. Other times, you can look at partials as a reusable subroutine. We'll explore each of these approaches and when to use them as well as the syntax for calling them.
Partials as a View Subroutine
Using the :locals option, you can pass a hash of values which will be treated as local variables within the partial template.
<%= render :partial => "person", :locals => { :name => "david" } %>
The variable name contains the value "david" within the _person.html.erb template. Passing variables in this way allows you to create modular, reusable template files. Note that if you want to make local variables that are optional in some use cases, you will have to set them to a sentinel value such as nil when they have not been passed. So, in the example above, if the name variable is optional in some use cases, you must set:
<% name ||= nil -%>
So that you can later check:
<% if name -%>
<p>Hello, <%= name %>!</p>
<% end -%>
Otherwise, the if statement will throw an error at runtime.
Another thing to be aware of is that instance variables that are visible to the parent view template are visible to the partial. So you might be tempted to do this:
<%= render :partial => "person" %>
And then within the partial:
<% if @name -%>
<p>Hello, <%= @name %>!</p>
<% end -%>
The potential snag here is that if multiple templates start to rely on this partial, you will need to maintain an instance variable with the same name across all of these templates and controllers. This approach can quickly become brittle if overused.
Partials as a View of an Object
Another way to look at partials is to view them as mini-views of a particular object or instance variable. Use the :object option to pass an object assigns that object to an instance variable named after the partial itself. For example:
# Renders the partial, making @new_person available through
# the local variable 'person'
render :partial => "person", :object => @new_person
If the instance variable name in the parent template matches the name of the partial, you can use a shortcut:
render :partial => "person"
Now the value that was in @person in the parent template is accessible as person in the partial.
Partials as a View of a Collection
Often it is the case that you need to display not just a single object, but a collection of objects. Rather than having to constantly nest the same partial within the same iterator code, Rails provides a syntactical shortcut using the :collection option:
# Renders a collection of the same partial by making each element
# of @winners available through the local variable "person" as it
# builds the complete response.
render :partial => "person", :collection => @winners
This calls the _person.html.erb partial for each person in the @winners collection. This also creates a local variable within the partial called partial_counter which contains the index of the current value. So for example:
<%= partial_counter %>) <%= person -%>
Where @winners contains three people, produces the following output:
1) Bill
2) Jeff
3) Nick
One last detail, you can place an arbitrary snippet of code in between the objects using the :spacer_template option.
# Renders the same collection of partials, but also renders the
# person_divider partial between each person partial.
render :partial => "person", :collection => @winners, :spacer_template => "person_divider"