How does local_assigns work in Rails?

Question

I've been googling around about this and can't find the right path. I'm working on a Rails app that is using a method called local_assigns. This appears to be something in Rails or a gem, and not specific to my app, but it's used for rendering a partial in different contexts, such as this:

<% if local_assigns[:custom_name] %>
  <li><%= custom_name %></li>
<% else %>

or also this:

<%= render "discussions/complementary/#{local_assigns[:action] || params[:action]}" %>

Is this is Rails method? Where can I find more documentation about this?

Solution

local_assigns is a Rails view helper method that you can check whether this partial has been provided with local variables or not.

Here you render a partial with some values, the headline and person will become accessible with predefined value.

<%= render "shared/header", { :headline => "Welcome", :person => person } %>

In shared/header view:

Headline: <%= headline %>
First name: <%= person.first_name %>

Here is how you check these variables has passed in or not:

<% if local_assigns.has_key? :headline %>
  Headline: <%= headline %>
<% end %>

Check this document for more detail on the section Passing local variables to sub templates.

Comments

[sockmonk]

When linking to Rails Guides, it would help to include the Rails version in the URL. That link for Rails 4.2.0 doesn't mention local_assigns that I can tell.

[mc9]

Rather than <% if local_assigns.has_key? :headline %>, why can't we just do <% if headline %>?

[Tim Diggins]

@MikeC this is because if headline is undefined (i.e. not passed to the partial) you'll get an NameError "undefined local variable or method..." raised rather than a falsey value.

[Eric Anderson]

Why cannot you just do if defined? headline then?

[medik]

@EricAnderson, because raising an error can save your life when debugging :).

[Joseph N.]

The guide also states "Testing using defined? headline will not work. This is an implementation restriction."

[Joshua Pinter]

@EricAnderson I'd like to add that local_assigns is much more explicit and clear when used in a partial. I ran into a confusing situation where I was testing for a local in a partial by the name of format. Using defined?( format ) would always pass because format is a Ruby method for String formatting. It was at this point that we decided to always use local_assigns when testing for the presence of locals in partials. I suggest you and yours adopt the same. It might save you minutes to hours of heartache in the future.

[Yurii Verbytskyi]

Interesting, but since Rails5 documentation changed from Testing using defined? headline will not work. This is an implementation restriction. to Alternatively, you could also use defined? headline to first check if the variable has been assigned before using it.