You can get a feel for ERb outside of Rails since the ERb interpreter is a standard part of Ruby, and you can write and process ERb templates for practice using that interpreter. You simply use the command-line command erb.

For example, put the following template code in a file (demo.erb, perhaps):

Let's list all the methods of a Ruby string.

First we need a string.

<% str = "I am a string!" %>

We've got one: here it is:

  <%= str %>

Now, let's see its methods:

<% str.methods.sort[0...10].each_with_index do |m,i| %>
  <%= i+1 %>. <%= m %>
<% end %>

Now, run the file through erb:

$ erb demo.erb

You’ll see the following output:

Let's list all the methods of a Ruby string.

First we need a string.



We've got one: here it is:

  I am a string!

Now, let's see its methods -- or maybe just a few, so they don't
scroll off the screen:


  1. %

  2. *

  3. +

  4. <

  5. <<

  6. <=

  7. <=>

  8. ==

  9. ===

  10. =~

As you can see, all of the Ruby code inside the delimiters has been executed, including the assignment to str and the iteration with each. Only the code inside the equal-sign delimiters, however, has contributed to the output from the execution of the template.

You may also notice a lot of blank lines in the output. The presence of delimited code in the template has no special effect, one way or the other, on the line count. A line is a line, so the following line comes through as a blank line:

<% end %>

Rails gives you a way to remove at least some of the extra blank lines, by using modified delimiters:

<%- str.methods.sort[0...10].each_with_index do |m,i| -%>
  <%= i+1 %>. <%= m %>
<%- end -%>

Note the minus signs in the delimiters; they will suppress leading whitespace and extra newlines in the output of the template. Used judiciously, they can pretty up your template output significantly. It isn’t something that the end user cares about, but it might help you out whenever you’re examining the HTML source code of your application.

Ruby’s commenting symbol # will work to cancel an ERb delimiter. Just insert it right after the percent sign of the opening delimiter tag.

<%#= str %>

The contents of the commented ERb tag will be ignored. You don’t want to leave commented-out code littering your template, but it’s useful for temporarily disabling something.

One of the most common idioms you’ll use when coding Rails views is to conditionally output content to the view. The most elementary way to control conditional output is to use if/else statements in conjunction with <% %> as follows:

<% if @show_subtitle %>
  <h2><%= @subtitle %></h2>
<% end %>

A lot of times you can use inline if conditions and shorten your code, since the <%= tag doesn’t care if you feed it a nil value. Just add a postfix if condition to the statement:

<h2><%= @subtitle if @show_subtitle %></h2>

Of course, there’s a potential problem with the preceding example. The first, more verbose, conditional output will eliminate the <h2> tags entirely, but the second example does not.

There are a couple of ways to deal with the problem and keep it a one-liner.

First, there’s the butt-ugly solution that I’ve occasionally seen in some Rails applications, which is the only reason why I’m mentioning it here!

<%= "<h2>#{@subtitle}</h2>" if @show_subtitle %>

Aaargh! Ugly! The more elegant solution involves Rails’ content_tag helper method.

<%= content_tag('h2', @subtitle) if @show_subtitle %>

Helper methods, both the ones included in Rails and the ones that you’ll write on your own, are your main tool for building elegant view templates. Helpers are covered extensively in Chapter 11, “All About Helpers.”

As of Rails 2.0 the standard naming practice is to suffix ERb template files with .erb, but in earlier versions of Rails, we used .rhtml.

There are two other standard formats and suffixes for templates:

Note that at the end of this chapter, we do a quick survey of third-party templating languages available that integrate nicely with Rails, and why you might want to try them. For now, let’s continue with a review of layout and template usage.

The Ruby language’s built-in yield keyword is put to good use in making layout and action templates collaborate. Notice the use of yield in the middle of the layout template:

<body>
  <%= yield :layout %>
</body>

In this case, the :layout symbol is a special message to the rendering system. It marks where to insert the output of the action’s rendered output, which is usually the template corresponding to that action.

You can add extra places in your layout where you want to be able to yield content, by including additional yield invocations—just make sure to use a unique identifier. A good example is a layout that has left and right sidebar content (simplified, of course):

<body>
  <div class="left sidebar">
    <%= yield :left %>
  </div>
  <div id="main_content">
    <%= yield :layout %>
  </div>
  <div class="right sidebar">
    <%= yield :right %>
  </div>
</body>

The center DIV element receives the main template content generated. But how do you give Rails content for the left and right sidebars? Easy—just use the content_for method in your template code in the following way:

<% content_for(:left) do %>
<h2>Navigation</h2>
<ul>
  <li>...
</ul>
<% end %>

<% content_for(:right) do %>
<h2>Help</h2>
<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit,
   sed do eiusmod tempor incididunt ut labore et dolore magna
   aliqua. Ut enim ad minim veniam, quis nostrud ...
<% end %>

<h1>Page Heading</h1>
<p>The normal template content that will get yielded
  to :layout</p>
  ...

Besides sidebars and other types of visible content blocks, I suggest you yield for additional content to be added to the HEAD element of your page, as shown in Listing 10.2. It’s a super-useful technique, because Internet Explorer can occasionally get very ill-tempered about SCRIPT tags appearing outside of the HEAD element.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">

<html>
 <head>
  <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
  <title>My Rails Application</title>
  <%= stylesheet_link_tag 'scaffold', :media => "all" %>
  <%= javascript_include_tag :defaults %>
  <%= yield :head %>
 </head>
 <body>
  <%= yield :layout %>
 </body>
</html>

We’ve seen how layouts and yielding content blocks work, but other than that, how does data get from the controller layer to the view? During preparation of the template, instance variables set during execution of the controller action will be copied over as instance variables of the template context.

class HelloWorldController < ActionController::Base
  def index
    @msg = "Hello, world!"
  end
end

# template file /app/views/hello_world/index.html.erb
<%= @msg %>

<html>
  ...
  <body class="<%= controller.controller_name %>
               <%= controller.action_name %>">
    ...
  </body>
</html>

<body class="timesheets index">

body.timesheets .header {
  background: url(../images/timesheet-bg.png) no-repeat left top
}

body.expense_reports .header {
  background: url(../images/expense-reports-bg.png) no-repeat left top
}

<html>
  ...
  <body>
    <%= content_tag 'div', h(flash[:notice]),
         :class => 'notice', :id => 'notice' if flash[:notice] %>
    <%= content_tag 'div', h(flash[:error]),
         :class => 'notice error', :id => 'error' if flash[:error] %>

    <%= yield :layout %>
  </body>
</html>

--
Status: 200 OK
cookie:
- - adf69ed8dd86204d1685b6635adae0d9ea8740a0
Cache-Control: no-cache

<p>Filter by month:
  <%= select_tag(:month_filter,
        options_for_select(@month_options, params[:month_filter])) %>

If any data in your application is user-submitted, or in any way originates from a source that you don’t trust completely, then you need to keep in mind the need to escape and sanitize template content. Otherwise, you leave yourself wide open to a variety of malicious hacker attacks.

For example, consider the following template snippet, which copies the value of params[:page_number] into its output quite innocently:

<h1>Search Results</h1>
<h2>Page <%= params[:page_number] %></h2>

Easy way to include the page number, right? Sure. But consider what happens if someone submits a request to that page that embeds a SCRIPT tag and some malicious code as the value of the page_number request parameter? Bingo! The malicious code goes right into your template!

Fortunately, there is a very simple way to prevent this form of attack and the Rails core developers expect you to use it very often, so they named the method with one character: h.

<h1>Search Results</h1>
<h2>Page <%=h(params[:page_number]) %></h2>

The h method escapes HTML content—instead of passing it through as markup, it will convert the less-than and greater-than characters into their respective character entities, and in so doing, cripple malicious injection attacks. Of course, it doesn’t do anything to content that doesn’t have markup.

But what if you are trying to display user-submitted HTML, as is often the case with web applications that feature blog-style commenting facilities? In those cases, you can try using the sanitize method of ActionView::Helpers::TextHelper. It’ll strip out the tags most commonly used in attacks: FORM and SCRIPT, but leave others intact. The sanitize method is covered in depth in Chapter 11.

The simplest partial use case is simply to extract a portion of template code. Some developers divide their templates into logical parts by using partial extraction. Sometimes it is easier to understand the structure of a screen if the significant parts are factored out of it. For instance, Listing 10.5 is a simple user registration screen that has its parts factored out into partials.

<h1>User Registration</h1>
<%= error_messages_for :user %>
<% form_for :user, :url => users_path do -%>
  <table class="registration">
   <tr>
    <td class="details demographics">
     <%= render :partial => 'details' %>
     <%= render :partial => 'demographics' %>
    </td>
    <td class="location">
     <%= render :partial => 'location' %>
    </td>
   </tr>
   <tr>
    <td colspan="2"><%= render :partial => 'opt_in' %></td>
   </tr>
   <tr>
    <td colspan="2"><%= render :partial => 'terms' %></td>
   </tr>
  </table>
  <p><%= submit_tag 'Register' %></p>
<% end -%>

While we’re at it, let me pop open one of those partials. To conserve space, we’ll take a look at one of the smaller ones, the partial containing the opt-in check boxes of this particular app. The source is in Listing 10.6; notice that its name begins with an underscore.

<fieldset id="opt_in">
  <legend>Spam Opt In</legend>
  <p><%= check_box :user, :send_event_updates %>
     Send me updates about events!<br/>
  <%= check_box :user, :send_site_updates%>
     Notify me about new services</p>
</fieldset>

Personally, I like partials to be entirely contained inside a semantically significant markup container. In the case of the opt-in partial in Listing 10.6, both check box controls are contained inside a single <fieldset> element, which I’ve given an id attribute. Following that rule, more as a loose guideline than anything else, helps me to mentally identify how the contents of this partial are going to fit inside the parent template. If we were dealing with other markup, perhaps outside of a form, I might choose to wrap the partial markup inside a well-identified <div> container, instead of a <fieldset>.

Why not include the <td> markup inside the partial templates? It’s a matter of style—I like to be able to see the complete markup skeleton in one piece. In this case, the skeleton is the table structure that you see in Listing 10.5. If portions of that table were inside the partial templates, it would obfuscate the layout of the page. I do admit that this is one of those areas where personal style and preference should take precedence and I can only advise you as to what has worked for me, personally.

Since the registration form is neatly factored out into its component parts, it is easy to create a simple edit form using some of its partials, as in Listing 10.7.

<h1>Edit User</h1>
<%= error_messages_for :user %>
<% form_for :user, :url => user_path(@user),
                   :html => { :method => :put } do -%>
  <table class="settings">
   <tr>
    <td class="details">
     <%= render :partial => 'details' %>
    </td>
    <td class="demographics">
     <%= render :partial => 'demographics' %>
    </td>
   </tr>
   <tr>
    <td colspan="2" class="opt_in">
      <%= render :partial => 'opt_in' %>
    </td>
   </tr>
  </table>
  <p><%= submit_tag 'Save Settings' %></p>
<% end -%>

If you compare Listings 10.5 and 10.7, you’ll notice that the structure of the table changed a little bit in the Edit form, and it has less content than the registration form. Perhaps the location is handled in greater detail on another screen, and certainly you don’t want to require agreement of terms every time the user changes her settings.

Until now we’ve been considering the use of partials that reside in the same directory as their parent template. However, you can easily refer to partials that are in other directories, just by prefixing the directory name. You still leave off the underscore, which might feel a little weird.

Let’s add a captcha partial to the bottom of the registration form from Listing 10.5, to help prevent spammers from invading our web application:

  ...
  <tr>
    <td colspan="2"><%= render :partial => 'terms' %></td>
   </tr>
   <tr>
    <td colspan="2"><%= render :partial => 'shared/captcha' %></td>
   </tr>
  </table>
  <p><%= submit_tag 'Register' %></p>
<% end -%>

Since the captcha partial is used in various different parts of the application, it makes sense to let it reside in a shared folder rather than any particular view folder. However, you do have to be a little bit careful when you move existing template code into a shared partial. It’s quite possible to inadvertently craft a partial that depends implicitly on where it’s rendered.

For example, take the case of the Rails-talk mailing list member with a troublesome partial defined in login/_login.rhtml:

<% form_tag do %>
 <label>Username:</label>
 <%= text_field_tag :username, params[:username] %>
 <br />
 <label>Password:</label>
 <%= password_field_tag :password, params[:password] %>
 <br />
 <%= submit_tag "Login" %>
<% end %>

The login form submission worked when he rendered this partial as part of the login controller’s login action (“the login page”), but not when it was included as part of the view for any other section of his website. The problem is that form_tag (covered in the next chapter) normally takes an optional action parameter telling it where to post its information. If you leave out the action, the form will post back to its current URL, which will vary for shared partials, depending on where they’re being used from.

Partials inherit the instance variables available to their parent templates. That’s why the form helpers used in the partials of Listings 10.5 and 10.7 work: They rely implicitly on an @user variable to be in scope. I feel it’s fine to use this implicit variable sharing in some cases, particularly when the partials are tightly bound to their parent templates. It would be especially true in cases where the only reason you broke out partials in the first place was to reduce the size and complexity of a particularly large template.

However, once you get into the practice of breaking out partial templates for application-wide reuse, depending on implicitly passed variables gets a lot more dicey. That’s why Rails supports the passing of locally scoped variables to partial templates, as a hash parameter named :locals, as in the following snippet:

render :partial => 'shared/address', :locals => { :form => form }

The names and values of the :locals hash are converted into locally scoped variables (no @ sign) in the partial. Listing 10.8 is a variation on the registration template. This time we’re using the version of form_for that yields a block parameter representing the form to its form helper methods. We’ll pass that form parameter on, too.

<h1>User Registration</h1>
<%= error_messages_for :user %>
<% form_for :user, :url => users_path do |form| -%>
  <table class="registration">
   <tr>
    <td class="details address demographics">
     <%= render :partial => 'details',
                :locals => {:form => form } %>
     <%= render :partial => 'shared/address',
                :locals => {:form => form } %>
    </td>
   </tr>
  </table>
  <p><%= submit_tag 'Register' %></p>
<% end -%>

And finally, in Listing 10.9 we have the shared address form.

<fieldset class="address">
  <legend>Address</legend>
  <p><label>Street</label><br/>
    <%= form.text_area :street, :rows => 2, :cols => 40 %></p>
  <p><label>City</label><br/>
    <%= form.text_field :city %></p>
  <p><label>State</label><br/>
    <%= form.text_field :state, :size => 2 %></p>
  <p><label>Zip</label><br/>
      <%= form.text_field :zip, :size => 15 %></p>
</fieldset>

The form helper methods, which we’ll cover in Chapter 11, have a variation in which they are called on the form variable yielded by the form_for method. That is exactly what we passed on to these partials via the :locals hash.

<% if local_assigns.has_key? :special %>
<%= special %>
<% end %>

One of the best uses of partials is to render collections. Once you get into the habit of rendering collections with partials, you won’t want to go back to the relative ugliness of cluttering your templates with for loops and each.

render :partial => 'entry', :collection => @entries

Simple and precise, and dependent on a naming convention. The most important is how the object being rendered is exposed to the partial template. It is set as a local variable named the same as the partial template itself. The partial corresponding to the last code snippet would reference a local variable named entry.

<%= div_for(entry) do %>
  <%= h(entry.description) %>
  <%= distance_of_time_in_words_to_now entry.created_at %> ago
<% end %>

<%= div_for(entry) do %>
  <%= entry_counter %>:
  <%= h(entry.description) %>
  <%= distance_of_time_in_words_to_now entry.created_at %> ago
<% end %>

render :partial => 'entry', :locals => {:entry => @entry }

<% entry = @entry if @entry %>
<% div_for(entry) do %>
  <%= h(entry.description) %>
  <%= distance_of_time_in_words_to_now entry.created_at %> ago
<% end %>

If you take a look at your development log, you’ll notice that it shows which partials have been rendered and how long they took.

Rendering template within layouts/application
Rendering listings/index
Rendered listings/_listing (0.00663)
Rendered listings/_listing (0.00296)
Rendered listings/_listing (0.00173)
Rendered listings/_listing (0.00159)
Rendered listings/_listing (0.00154)
Rendered layouts/_login (0.02415)
Rendered layouts/_header (0.03263)
Rendered layouts/_footer (0.00114)

I wanted to mention up front that caching is disabled in development mode. If you want to play with caching, you’ll need to edit the following setting in the config/environments/development.rb file:

config.action_controller.perform_caching             = false

Of course, remember to change it back before checking it back into your project repository, or you might face some very confusing errors down the road.^[1]

The simplest form of caching is page caching, triggered by use of the caches_page macro-style method in a controller. It tells Rails to capture the entire output of the request to disk so that it is served up directly by the web server on subsequent requests without the involvement of the dispatcher. Nothing will be logged to the Rails log, nor will controller filters be triggered—absolutely nothing to do with Rails will happen, just like the static HTML files in your project’s public directory.

By definition, if there’s anything that has to change on every request or specific to an end user’s view of that page, page caching is not an option. On the other hand, if all we need to do is run some filters that check conditions before displaying the page requested, the caches_action method will work. It’s almost like page caching, except that controller filters are executed prior to serving the cached HTML file. That gives you the option to do some extra processing or even redirect if necessary.

Action caching is implemented with fragment caching (covered later in this chapter) and an around filter (covered in Chapter 2, “Working with Controllers”). The cached action content is keyed based on the current host and the path, which means that it will still work even with Rails applications serving multiple subdomains using a DNS wildcard. Also, different representations of the same resource, such as HTML and XML, are treated like separate requests and cached separately.

We’ll use our lil_journal^[2] sample application as the basis for our code snippets in this section. The application should have public versus private entries, so for default requests, we should run a filter that figures out whether the visitor is logged in and redirects them to the public action if necessary. Listing 10.10 has the EntriesController code.

class EntriesController < ApplicationController

  before_filter :check_logged_in, :only => [:index]

  caches_page :public
  caches_action :index

  def public
    @entries = Entry.find(:all,
                          :limit => 10,
                          :conditions => {:private => false})

    render :action => 'index'
  end

  def index
    @entries = Entry.find(:all, :limit => 10)
  end

  private

    def check_logged_in
      redirect_to :action => 'public' unless logged_in?
    end

end

The public action displays only the public entries and is visible to anyone, which makes it a candidate for page caching. However, since it doesn’t require its own template, we just call render :action => 'index' explicitly at the end of the public action.

def index
  opts = {}
  opts[:limit] = 10
  opts[:conditions] = {:private => false } unless logged_in?
  @posts = Entry.find(:all, opts)
end

Users are accustomed to all sorts of dynamic content on the page, and your application layout will be filled with things like welcome messages and notification counts. Fragment caching allows us to capture parts of the rendered page on disk and serve them up on subsequent requests without needing to render their content again. The performance improvement is not as dramatic as with page or action caching, since the Rails dispatcher is still involved. However, you can still give your application a blazing speed boost by using fragment caching.

<%= content_tag :h1, "#{@user.name}'s Journal" %>
<% cache do %>
  <%= render :partial => 'entry', :collection => @entries %>
<% end %>

<% cache "my_fragment" do %>

<%= content_tag :h1, "#{@user.name}'s Journal" %>

<% cache(:fragment => 'entries') do %>
  <%= render :partial => 'entry', :collection => @entries %>
<% end %>

<%- content_for :sidebar -%>

  <% cache(:fragment => 'recent_comments') do %>
    <%= render :partial => 'comment', :collection => @recent_comments
%>
  <% end %>

<% end %>

<%= content_tag :h1, "#{@user.name}'s Journal" %>

<% cache(:fragment => 'entries') do %>
  <%= render :partial => 'entry', :collection => @entries %>
<% end %>

<%- content_for :sidebar -%>

  <% cache(@user.name + "_stats") do %>
    <%= render :partial => 'stats' %>
  <% end %>

  <% cache(:fragment => 'recent_comments') do %>
    <%= render :partial => 'comment', :collection => @recent_comments %>
  <% end %>

<% end %>

def index
  unless read_fragment(:fragment => 'entries')
    @entries = Entry.find(:all, :limit => 10)
  end
end

Whenever you use caching, you need to consider any and all situations that will cause the cache to become stale, out of date. Then you need to write code that sweeps away the old content, so to speak, making room for new content to be cached in its place.

1  def create
2    @entry = @user.entries.build(params[:entry])
3    if @entry.save
4      expire_page :action => 'public'
5      redirect_to entries_path(@entry)
6    else
7      render :action => 'new'
8    end
9  end

def create
  @entry = @user.entries.build(params[:entry])
  if @entry.save
    expire_page :action => 'public'
    expire_fragment(:fragment => 'entries')
    expire_fragment(:fragment => (@user.name + "_stats"))
    redirect_to entries_path(@entry)
  else
    render :action => 'new'
  end
end

expire_fragment(r%{entries/.*})

A Sweeper class is kind of like an ActiveRecord Observer object, except that it’s specialized for use in expiring cached content. When you write a sweeper, you tell it which of your models to observe for changes, just as you would with callback classes and observers.

Listing 10.15 is a sweeper to keep the caching of Lil’ Journal’s entries in order.

class EntrySweeper < ActionController::Caching::Sweeper
  observe Entry

  def expire_cached_content(entry)
    expire_page :controller => 'entries', :action => 'public'
    expire_fragment(r%{entries/.*})
    expire_fragment(:fragment => (entry.user.name + "_stats"))
  end

  alias_method :after_save, :expire_cached_content
  alias_method :after_destroy, :expire_cached_content

end

Once you have a Sweeper class (put it in your app/models directory), you need to tell your controller to use that sweeper in conjunction with its actions. Here’s the top of the revised entries controller for Lil’ Journal:

class EntriesController < ApplicationController

  before_filter :check_logged_in, :only => [:index]
  caches_page :public
  cache_sweeper :entry_sweeper, :only => [:create, :update, :destroy]

  ...

Like many other controller macros, the cache_sweeper method takes :only and :except options. There’s no need to bother the sweeper for actions that can’t modify the state of the application, so we do indeed include the :only option in our example.

Like the related observers, sweepers are not limited to observing just one model. The main thing to remember if we go down that route is that our callback methods will need to know how to handle all of them. Ruby’s case statement may come in handy, as shown in Listing 10.16, a full revision of the EntrySweeper, which may now observe Comment as well as Entry objects.

class EntrySweeper < ActionController::Caching::Sweeper
  observe Entry, Comment

  def expire_cached_content(record)
    expire_page :controller => 'entries', :action => 'public'
    expire_fragment(r%{entries/.*})

    user = case entry
      when Entry then record.user
      when Comment then record.entry.user
    end

    expire_fragment(:fragment => (user.name + "_stats"))
  end

  alias_method :after_save, :expire_cached_content
  alias_method :after_destroy, :expire_cached_content

end

If you’ve turned on caching during development, you can actually monitor the Rails log for messages about caching and expiration.

Processing Entries#index (for 127.0.0.1 at 2007-07-20 23:07:09) [GET]
 ...
Cached page: /entries.html (0.03949)


Processing Entries#create (for 127.0.0.1 at 2007-07-20 23:10:50)
[POST]
 ...
Expired page: /entries.html (0.00085)

It’s a good way to see whether your caching is actually working as expected.

The Action Cache plugin by Tom Fakes and Scott Laird is a recommended drop-in replacement for the built-in Rails caching facilities. It doesn’t change the Caching API at all, only the underlying implementation.

script/plugin install http://craz8.com/svn/trunk/plugins/action_cache

These are the major features of the Action Cache plugin:

Unlike session data, fragment-cached data can grow to be quite large. Rails gives you four different options for cache storage:

ActionController::Base.fragment_cache_store = :memory_store

ActionController::Base.fragment_cache_store = :file_store,
"/path/to/cache/directory"
ActionController::Base.fragment_cache_store = :drb_store,
"druby://localhost:9192"
ActionController::Base.fragment_cache_store = :mem_cache_store,
"localhost"

desc "Manually sweep the cache"
task :cache_sweeper do
  FileUtils.rm_rf Dir[File.join(RAILS_ROOT, "public", "entries*")]
#pages
  FileUtils.rm_rf Dir[File.join(RAILS_ROOT, "tmp", "cache*")]
#fragments
end