The error_message_on and error_messages_for methods help you to add formatted validation error information to your templates in a consistent fashion.

<div class="form_field">
  <div class="field_label">
    <span class="required">*</span>
    <label>First Name</label>
  </div>
  <div class="textual">
    <%= form.text_field :first_name, :maxlength => 34, :tabindex => 1
%>
    <%= error_message_on :user, :first_name %>
  </div>
</div>

def error_messages_for(*params)
  options = params.last.is_a?(Hash) ? params.pop.symbolize_keys : {}
  objects = params.collect { |object_name|
              instance_variable_get("@#{object_name}")
            }.compact

  count = objects.inject(0) {|sum, object| sum + object.errors.count }
  unless count.zero?
    html = {}
    [:id, :class].each do |key|
      if options.include?(key)
        value = options[key]
        html[key] = value unless value.blank?
      else
        html[key] = 'errorExplanation'
      end
    end

    header_message = "#{pluralize(count, 'error')} prohibited this
    #{(options[:object_name] || params.first).to_s.gsub('_', ' ')}
    from being saved"

    error_messages = objects.map {|object|
      object.errors.full_messages.map {|msg| content_tag(:li, msg)}
    }

    content_tag(:div,
      content_tag(options[:header_tag] || :h2, header_message) <<
      content_tag(:p, 'There were problems with the following fields:') <<
      content_tag(:ul, error_messages), html )
  else
    ''
  end
end

The next couple of methods are used for automatic field creation by the scaffolding code. You can try using them too, but I suspect that their usefulness is somewhat limited in real applications.

> form("post")

=> <form action='/post/create' method='post'>
     <p>
       <label for="post_title">Title</label><br/>
       <input id="post_title" name="post[title]"
              size="30" type="text" value="Hello World" />
     </p>
     <p>
        <label for="post_body">Body</label><br/>
        <textarea cols="40" id="post_body" name="post[body]"
rows="20">
          Back to the hill and over it again!
        </textarea>
     </p>
     <input type='submit' value='Create' />
   </form>

> form("entry", :action => "sign",
    :input_block => Proc.new { |record, column|
      "#{column.human_name}: #{input(record, column.name)}<br/>" })

=> <form action='/post/sign' method='post'>
     Message:
     <input id="post_title" name="post[title]" size="30"
            type="text" value="Hello World" /><br />
     <input type='submit' value='Sign' />
   </form>

form("entry", :action => "sign") do |s|
  s << content_tag("b", "Department")
  s << collection_select("department", "id", @departments, "id",
"name")
end

input("post", "title")

=> <input id="post_title" name="post[title]" size="30"
          type="text" value="Hello World" />

def to_tag(options = {})
  case column_type
    when :string
      field_type = @method_name.include?("password") ? "password" :
"text"
      to_input_field_tag(field_type, options)
    when :text
      to_text_area_tag(options)
    when :integer, :float, :decimal
      to_input_field_tag("text", options)
    when :date
      to_date_select_tag(options)
    when :datetime, :timestamp
      to_datetime_select_tag(options)
    when :time
      to_time_select_tag(options)
    when :boolean
      to_boolean_select_tag(options)
  end
end

By default, when Rails marks a field in your form that failed a validation check, it does so by wrapping that field in a DIV element, with the class name fieldWithErrors. This behavior is actually customizable, since it is accomplished via a Proc object stored as a configuration property of the ActionView::Base class:

module ActionView
  class Base
    @@field_error_proc = Proc.new { |html_tag, instance|
      "<div class="fieldWithErrors">#{html_tag}</div>"
    }
    cattr_accessor :field_error_proc
  end

  ...

Armed with this knowledge, changing the validation error behavior is as simple as overriding ActionView’s field_error_proc attribute with your own custom Proc. I would suggest doing so either in config/environment.rb or your ApplicationController class.

In Listing 11.1, I changed the setting so that the input fields with validation errors are prefixed with a red ERR message.

ActionView::Base.field_error_proc =
   Proc.new do |html_tag,instance|
     %(<div style="color:red">ERR</div>) + html_tag
   end

It has been suggested by many people that it would have been a much better default solution to simply add a fieldWithErrors CSS class to the input tag itself, instead of wrapping it with an extra DIV tag. Indeed, that would have made many of our lives easier, since an extra DIV often breaks pixel-perfect layouts. However, since html_tag is already constructed at the time when the field_error_proc is invoked, it is not trivial to modify its contents.

There are some solutions out there that use regular expressions and modify the html_tag string, for instance this one, found at http://snippets.dzone.com/tag/field_error_proc:

ActionView::Base.field_error_proc = Proc.new do |html_tag, instance|
  error_style = "background-color: #ffff80"
  if html_tag =~ /<(input|textarea|select)[^>]+style=/
    style_attribute = html_tag =~ /style=['"]/
    html_tag.insert(style_attribute + 7, "#{error_style}; ")
  elsif html_tag =~ /<(input|textarea|select)/
    first_whitespace = html_tag =~ /s/
    html_tag[first_whitespace] = " style='#{error_style}' "
  end
  html_tag
end

Ugly! This is certainly an area of ActionView that could use improvement.

Most of the helper methods in this module help you add content to the HEAD of your HTML document.

auto_discovery_link_tag # =>
  <link rel="alternate" type="application/rss+xml" title="RSS"
  href="http://www.curenthost.com/controller/action" />

auto_discovery_link_tag(:atom) # =>
  <link rel="alternate" type="application/atom+xml" title="ATOM"
  href="http://www.curenthost.com/controller/action" />

auto_discovery_link_tag(:rss, {:action => "feed"}) # =>
  <link rel="alternate" type="application/rss+xml" title="RSS"
  href="http://www.curenthost.com/controller/feed" />

auto_discovery_link_tag(:rss, {:action => "feed"}, {:title => "My
RSS"}) # =>
  <link rel="alternate" type="application/rss+xml" title="My RSS"
  href="http://www.curenthost.com/controller/feed" />

auto_discovery_link_tag('image/x-icon', 'favicon.ico',
  :rel => 'shortcut icon', :title => '')

<link rel="shortcut icon" href="favicon.ico"
type="image/x-icon" title="">

image_path("edit.png")  # => /images/edit.png
image_path("icons/edit.png")  # => /images/icons/edit.png
image_path("/icons/edit.png")  # => /icons/edit.png

image_tag("icon.png")  # =>
  <img src="/images/icon.png" alt="Icon" />

image_tag("icon.png", :size => "16x10", :alt => "Edit Entry")  # =>
  <img src="/images/icon.png" width="16" height="10" alt="Edit Entry"
/>

image_tag("/photos/dog.jpg", :class => 'icon')  # =>
  <img src="/photos/icon.gif" alt="Dog" class="icon"/>

javascript_include_tag "xmlhr", :defer => 'defer' # =>
  <script type="text/javascript" src="/javascripts/xmlhr.js"
  defer="defer"></script>

javascript_include_tag "common.javascript", "/elsewhere/cools" # =>
  <script type="text/javascript"
src="/javascripts/common.javascript"></script>
  <script type="text/javascript" src="/elsewhere/cools.js"></script>

javascript_include_tag :defaults # =>
  <script type="text/javascript"
src="/javascripts/prototype.js"></script>
  <script type="text/javascript"
src="/javascripts/effects.js"></script>
  ...
  <script type="text/javascript"
src="/javascripts/application.js"></script>

stylesheet_link_tag "style" # =>
  <link href="/stylesheets/style.css" media="screen"
        rel="Stylesheet" type="text/css" />

stylesheet_link_tag "style", :media => "all" # =>
  <link href="/stylesheets/style.css" media="all"
        rel="Stylesheet" type="text/css" />

stylesheet_link_tag "random.styles", "/css/stylish" # =>
  <link href="/stylesheets/random.styles" media="screen"
        rel="Stylesheet" type="text/css" />
  <link href="/css/stylish.css" media="screen"
        rel="Stylesheet" type="text/css" />

The register_javascript_include_default class method of ActionView::Helpers::AssetTagHelper lets plugin authors register one or more additional JavaScript files to be included when javascript_include_tag :defaults is called. This method is only intended to be called from plugin initialization to register additional .js files that the plugin installed in public/javascripts. You can find more details about this method in Chapter 19, “Extending Rails with Plugins.”

Measures the execution time of a block in a template and reports the result to the log.

<% benchmark "Notes section" do %>
  <%= expensive_notes_operation %>
<% end %>

The preceding example will add something like “Notes section (0.34523)” to the log when the template is executed. It’s possible to give an optional logger level as the second argument (:debug, :info, :warn, :error), but the default is :info.

The capture method lets you capture part of a template’s output (inside a block) and assign it to an instance variable. The value of that variable can subsequently be used anywhere else on the template.

<% @message_html = capture do %>
<div>This is a message</div>
<% end %>

I don’t think that the capture method is really that useful on its own in a template. It’s a lot more useful when you use it in your own custom helper methods. It gives you the ability to write your own helpers that grab template content wrapped using a block. We cover that technique later on in this chapter in the section “Writing Your Own Helpers.”

We mentioned the content_for method in Chapter 10 in the section “Yielding Content.” It allows you to designate a part of your template as content for another part of the page. It works similarly to its sister method capture (in fact, it uses capture itself). Instead of returning the contents of the block provided to it, it stores the content to be retrieved using yield elsewhere in the template (or most commonly, in the surrounding layout).

A common example is to insert “sidebar” content into a layout. In the following example, the link will not appear in the “flow” of the view template—it will appear elsewhere in the template, wherever <%= yield :navigation_sidebar %> appears.

<% content_for :navigation_sidebar do %>
  <%= link_to 'Detail Page', item_detail_path(item) %>
<% end %>

The following methods help you create form field input tags dealing with date and time data. All of them are prepared for multiparameter assignment to an ActiveRecord object. That’s a fancy way of saying that even though they appear in the HTML form as separate input fields, when they are posted back to the server, it is understood that they refer to a single attribute of the model. That’s some Rails magic for you!

date_select("post", "written_on")

date_select("post", "written_on", :start_year => 1995,
                                  :use_month_numbers => true,
                                  :discard_day => true,
                                  :include_blank => true)

date_select("post", "written_on", :order => [:day, :month, :year])

date_select("user", "birthday",   :order => [:month, :day])

time_select("post", "sunrise")
time_select("post", "start_time", :include_seconds => true)

Sometimes you need just a particular element of a date or time, and Rails obliges you with a comprehensive set of individual date and time select helpers. In contrast to the date and time helpers that we just looked at, the following helpers are not bound to an instance variable on the page. Instead, they all take a date or time Ruby object as their first parameter. (All of these methods have a set of common options, covered in the following subsection.)

# Will use keys like "January", "March"
select_month(Date.today)

# Will use keys like "1", "3"
select_month(Date.today, :use_month_numbers => true)

# Will use keys like "1 - January", "3 - March"
select_month(Date.today, :add_month_numbers => true)

# Will use keys like "Jan", "Mar"
select_month(Date.today, :use_short_month => true)

# Will use keys like "Januar", "Marts"
select_month(Date.today, :use_month_names => %w(Januar Februar
Marts ...))

# ascending year values
select_year(Date.today, :start_year => 1992, :end_year => 2007)

# descending year values
select_year(Date.today, :start_year => 2005, :end_year => 1900)

All of the select-type methods share a number of common options that are as follows:

Some distance_in_time methods have really long, complex descriptive names that nobody can ever remember without looking them up. Well, at least for the first dozen times or so you might not remember.

I find the following methods to be a perfect example of the Rails way when it comes to API design. Instead of going with a shorter and necessarily more cryptic alternative, the framework author decided to keep the name long and descriptive. It’s one of those cases where a nonprogrammer can look at your code and understand what it’s doing. Well, probably.

I also find these methods remarkable in that they are part of why people sometimes consider Rails part of the Web 2.0 phenomenon. What other web framework would include ways to humanize the display of timestamps?

def distance_of_time_in_words(from_time, to_time = 0, include_seconds =
false)

  from_time = from_time.to_time if from_time.respond_to?(:to_time)
  to_time = to_time.to_time if to_time.respond_to?(:to_time)

  d_minutes = (((to_time - from_time).abs)/60).round
  d_seconds = ((to_time - from_time).abs).round

  case d_minutes
    when 0..1
      unless include_seconds
        return (d_minutes==0) ? 'less than a minute' : '1 minute'
      end

      case d_seconds
        when 0..4   then 'less than 5 seconds'
        when 5..9   then 'less than 10 seconds'
        when 10..19 then 'less than 20 seconds'
        when 20..39 then 'half a minute'
        when 40..59 then 'less than a minute'
        else             '1 minute'
      end

    when 2..44      then "#{d_minutes} minutes"
    when 45..89     then 'about 1 hour'
    when 90..1439   then "about #{(d_minutes.to_f/60.0).round} hours"
    when 1440..2879      then '1 day'
    when 2880..43199     then "#{(d_minutes / 1440).round} days"
    when 43200..86399    then 'about 1 month'
    when 86400..525599   then "#{(d_minutes / 43200).round} months"
    when 525600..1051199 then 'about 1 year'
    else                      "over #{(d_minutes / 525600).round}
years"
  end
end

<strong><%= comment.user.name %></strong><br/>
<small><%= distance_of_time_in_words_to_now review.created_at %>
ago</small>

The core method of this helper is called form_for, and we covered it to some extent in Chapter 4, “REST, Resources, and Rails.” You pass it the name of the model you want to create a form for (or the model instance itself), as its first parameter, followed by URL information for the HTML form’s action attribute. The helper method yields a form object, on which you can invoke input helper methods, omitting their first argument.

Assume we want a form for the user to create a new Person record and additionally assume that @person = Person.new happened in the action of the controller that is rendering this template code:

<% form_for :person, @person, :url => { :action => "create" } do
|form| %>
  <%= form.text_field :first_name %>
  <%= form.text_field :last_name %>
  <%= submit_tag 'Create' %>
<% end %>

This is the equivalent (old-school) version of form_for, which doesn’t use a yielded form object and explicitly names the object being used in the input fields:

<% form_for :person, @person, :url => { :action => "create" } do %>
  <%= text_field :person, :first_name %>
  <%= text_field :person, :last_name %>
  <%= submit_tag 'Create' %>
<% end %>

The first version has less repetition (remember your DRY principle), but don’t forget the more verbose style entirely—it’s necessary in some circumstances.

<form action="/persons/create" method="post">
  <input id="person_first_name" name="person[first_name]" size="30"
type="text" />
  <input id="person_last_name" name="person[last_name]" size="30"
type="text" />
  <input name="commit" type="submit" value="Create" />
</form>

Parameters: {"commit"=>"Create", "action"=>"create",
"controller"=>"persons",
 "person"=> {"first_name"=>"William", "last_name"=>"Smith"}}

<form action="/persons/create" method="post">
  <input id="person_first_name" name="person[first_name]" size="30"
type="text" value="Obie"/>
  <input id="person_last_name" name="person[last_name]" size="30"
type="text" value="Fernandez"/>
  <input name="commit" type="submit" value="Create" />
</form>

def new
  @person = Person.new(:first_name => 'First', :last_name => 'Last')
end

<% form_for "person[]" do |form| %>
 <% for @person in @people %>
  <%= form.text_field :name %>
  ...

<input type="text" id="person_8_name" name="person[8][name]"
 value="Obie Fernandez"/>

Parameters: {"person"=>{"8"=>{"name"=>"Obie Fernandez"},
                        "9"=>{"name"=>"Jodi Showers"}, ...}, ... }

NoMethodError (undefined method `8=' for #<User:0x8762174>):
    /vendor/rails/activerecord/lib/active_record/base.rb:2032:in
`method_missing'

Person.update(params[:person].keys, params[:person].values)

<input type="text" id="person__name" name="person[][name]"/>

def add_people
  Person.create(params[:person])
  ...
end

DISPATCHER FAILSAFE RESPONSE (has cgi) Sun Jul 15 14:36:35 -0400 2007
  Status: 500 Internal Server Error
  Conflicting types for parameter containers. Expected an instance of
  Hash but found an instance of Array. This can be caused by colliding
  Array and Hash parameters like qs[]=value&qs[key]=value.

<% for @person in @people %>
<%= text_field :person, :name, :index => @person.id %>
...

<% form_for :team do |f|%>
  <h2>Team Name</h2>
  Name: <%= f.text_field :name %><br/>
  Coach: <%= f.text_field :coach %>
  <% ["guard_1", "guard_2", "forward_1", "forward_2", "center"].each
{|role| %>
    <h3><%= role.humanize %></h3>
    Name: <%= text_field :players, :name, :index => role %>
  <% } %>
<% end %>

<form method="post" action="/homepage/team">
  <h2>Team Name</h2>
  Name: <input id="team_name" type="text" size="30"
name="team[name]"/><br/>
  Coach: <input id="team_coach" type="text" size="30"
name="team[coach]"/>
  <h3>Guard 1</h3>
  Name: <input id="players_guard_1_name" type="text" size="30"
  name="players[guard_1][name]"/>
  <h3>Guard 2</h3>
  Name: <input id="players_guard_2_name" type="text" size="30"
  name="players[guard_2][name]"/>
  <h3>Forward 1</h3>
  Name: <input id="players_forward_1_name" type="text" size="30"
  name="players[forward_1][name]"/>
  <h3>Forward 2</h3>
  Name: <input id="players_forward_2_name" type="text" size="30"
  name="players[forward_2][name]"/>
  <h3>Center</h3>
  Name: <input id="players_center_name" type="text" size="30"
  name="players[center][name]"/>
</form>

Parameters: {"team"=>{
               "name"=>"Chicago Bulls",
               "coach"=>"Phil Jackson"},
            {"players"=> {
                "forward_1"=>{"name"=>"Scottie Pippen"},
                "forward_2"=>{"name"=>"Horace Grant"},
                "center"=>{"name"=>"Bill Cartwright"},
                "guard_1"=>{"name"=>"Michael Jordan"},
                "guard_2"=>{"name"=>"John Paxson"}}, ... }

def create
  @team = Team.create(params[:team])
  params[:players].keys.each do |role|
    @team.add_player(role, Player.new(params[:players][role]))
  end
  ...
end

def create
  @team = Team.create(params[:team])
  ...
end

class Team < ActiveRecord::Base
  has_many :positions
  has_many :players, :through => :positions

  def players=(players_hash)
    players_hash.keys.each do |role|
      positions.create(:role => role,
                       :player => Player.new(players_hash[role]))
    end
  end
end

class Position < ActiveRecord::Base
  belongs_to :player
  belongs_to :team
end

class Player < ActiveRecord::Base
  has_many :positions
  has_many :teams, :through => :positions
end

A rather important lesson to learn about Rails form helper methods is that the value they display comes directly from the database prior to “meddling” by the developer. Unless you know what you’re doing, you may get some unexpected results if you try to override the values to be displayed in a form.

Let’s illustrate with a LineItem model, which has a decimal rate attribute (by merits of a rate column in its database table). We’ll override its implicit rate accessor with one of our own:

class LineItem < ActiveRecord::Base
  def rate
    "A RATE"
  end
end

In normal situations, the overridden accessor is hiding access to the real rate attribute, as we can illustrate using the console.

>> li = LineItem.new
=> #<LineItem:0x34b5d18>
>> li.rate
=> "A RATE"

However, suppose you were to compose a form to edit line items using form helpers:

<%- form_for :line_item do |f| -%>
  <%= f.text_field :rate %>
<%- end -%>

You would find that it works normally, as if that overridden rate accessor doesn’t exist. The behavior is intentional, yet confusing enough that it has been reported multiple times as a bug.^[2]

The fact is that Rails form helpers use special methods named attribute_before_type_cast (which are covered in Chapter 6, “Working with ActiveRecord”). The preceding example would use the method rate_before_type_cast, and bypass the overriding method we defined.

The following methods help you to create select tags based on a pair of object and attribute identifiers.

<%= form.country_select :billing_country, ["United States"] %>

select("post", "person_id", Person.find(:all).collect {|p|
[ p.name, p.id ] }, { :include_blank => true })

<select name="post[person_id]">
  <option value=""></option>
  <option value="1" selected="selected">David</option>
  <option value="2">Sam</option>
  <option value="3">Tobias</option>
</select>

For all of the following methods, only option tags are returned, so you have to invoke them from within a select helper or otherwise wrap them in a select tag.

>> html_option_groups_from_collection(@continents, "countries",
   "continent_name", "country_id", "country_name",
@selected_country.id)

<optgroup label="Africa">
 <select>Egypt</select>
 <select>Rwanda</select>
 ...
</optgroup>
<optgroup label="Asia">
 <select>China</select>
 <select>India</select>
 <select>Japan</select>
 ...
</optgroup>

class Continent
  def initialize(p_name, p_countries)
    @continent_name = p_name; @countries = p_countries
  end

  def continent_name
    @continent_name
  end

  def countries
    @countries
  end
end

class Country
  def initialize(id, name)
    @id, @name = id, name
  end

  def country_id
    @id
  end

  def country_name
    @name
  end
end

class Business < ActiveRecord::Base
  belongs_to :category
end

class Category < ActiveRecord::Base
  has_many :businesses

  def <=>(other)
end

<% opts = @businesses.map(&:category).sort.collect {|c| [[c.name],
[c.id]]} %>
<% select_tag(:filter, options_for_select(opts, params[:filter])) %>

... @businesses.map(&:category).uniq.sort.collect {...

@businesses = Business.find(:conditions => ..., :include => :category)

>> options_for_select([["Dollar", "$"], ["Kroner", "DKK"]])
   <option value="$">Dollar</option>
   <option value="DKK">Kroner</option>

>> options_for_select([ "VISA", "MasterCard" ], "MasterCard")
   <option>VISA</option>
   <option selected="selected">MasterCard</option>

>> options_for_select({ "Basic" => "$20", "Plus" => "$40" }, "$40")
   <option value="$20">Basic</option>
   <option value="$40" selected="selected">Plus</option>

>> options_for_select([ "VISA", "MasterCard", "Discover" ],
                      ["VISA", "Discover"])
    <option selected="selected">VISA</option>
    <option>MasterCard</option>
    <option selected="selected">Discover</option>

>> options_for_select({ "Basic" => "20", "Plus" => "40" }, price.to_s)
   <option value="20">Basic</option>
   <option value="40" selected="selected">Plus</option>

Creates HTML for a check box input field. Unlike its fancier cousin, check_box in FormHelper, this helper does not give you an extra hidden input field to ensure that a false value is passed even if the check box is unchecked.

>> check_box_tag('remember_me')
=> <input id="remember_me" name="remember_me" type="checkbox"
value="1"/>

>> check_box_tag('remember_me', 1, true)
=> <input checked="checked" id="remember_me" name="remember_me"
   type="checkbox" value="1" />

Prior to Rails 2.0, the end_form_tag was used to output the HTML string </form> into your template, and was used in conjunction with start_form_tag. Nowadays, we use a block to wrap the content of a form and this method is no longer needed.

Creates a file upload field. Remember to set your HTML form to multipart or file uploads will mysteriously not work:

<%= form_tag { :action => "post" }, { :multipart => true } %>
  <label for="file">File to Upload</label>
  <%= file_field_tag :uploaded_data %>
  <%= submit_tag %>
<%= end_form_tag %>

The controller action will receive a File object pointing to the uploaded file as it exists in a tempfile on your system. Processing of an uploaded file is beyond the scope of this book. If you’re smart, you’ll use Rick Olson’s excellent AttachmentFu^[3] plugin instead of rolling your own handler code.

Starts a FORM tag, with its action attribute set to the URL passed as the url_for_options parameter. It is aliased as start_form_tag.

The :method option defaults to POST. Browsers handle HTTP GET and POST natively; if you specify “put,” “delete,” or any other HTTP verb is used, a hidden input field will be inserted with the name _method and a value corresponding to the method supplied. The Rails request dispatcher understands the _method parameter, which is the basis for the RESTful techniques you learned in Chapter 4.

The :multipart option allows you to specify that you will be including file-upload fields in the form submission and the server should be ready to handle those files accordingly.

>> form_tag('/posts')
=> <form action="/posts" method="post">

>> form_tag('/posts/1', :method => :put)
=> <form action="/posts/1" method="put">

>> form_tag('/upload', :multipart => true)
=> <form action="/upload" method="post" enctype="multipart/form-data">

You might note that all parameters to form_tag are optional. If you leave them off, you’ll get a form that posts back to the URL that it came from—a quick and dirty solution that I use quite often when prototyping or experimenting. To quickly set up a controller action that handles post-backs, just include an if/else condition that checks the request method, something like this:

def add
  if request.post?
    # handle the posted params
    redirect_to :back
  end
end

Notice that if the request is a post, I handle the form params and then redirect back to the original URL (using redirect_to :back). Otherwise, execution simply falls through and would render whatever template is associated with the action.

Creates a hidden field, with parameters similar to text_field_tag.

Displays an image that, when clicked, will submit the form. The interface for this method is the same as its cousin image_tag in the AssetTagHelper module.

Image input tags are popular replacements for standard submit tags, because they make an application look fancier. They are also used to detect the location of the mouse cursor on click—the params hash will include x and y data.

Creates a password input field. This method is otherwise identical to text_field_tag.

Creates a radio button input field. Make sure to give all of your radio button options the same name so that the browser will consider them linked.

Creates a drop-down selection box, or if the :multiple option is set to true, a multiple-choice selection box. The option_tags parameter is an actual string of option tags to put inside the select tag. You should not have to generate that string explicitly yourself—use the helpers in FormOptions (covered in the previous section of this chapter), which can be used to create common select boxes such as countries, time zones, or associated records.

Alias for form_tag.

Creates a submit button with the text value as the caption. The option :disable_with can be used to provide a name for disabled versions of the submit button.

Creates a multiline text input field (the TEXTAREA tag). The :size option lets you easily specify the dimensions of the text area, instead of having to resort to explicit :rows and :cols options.

>> <%= text_area_tag "body", nil, :size => "25x10" %>
=> <textarea name="body" id="body" cols="25" rows="10"></textarea>

Creates a standard text input field.

Returns a button that will trigger a JavaScript function via the onclick handler. The function argument can be left out, if you provide an update_page block containing RJS-style code. The opts hash takes optional attributes for the button tag.

button_to_function "Greeting", "alert('Hello world!')"

button_to_function "Delete", "if (confirm('Really?')) do_delete()"

button_to_function "Details" do |page|
  page[:details].visual_effect :toggle_slide
end

button_to_function "Details", :class => "details_button" do |page|
  page[:details].visual_effect :toggle_slide
end

Includes the source code for all of your project’s JavaScript libraries inside a single SCRIPT tag. The function first includes prototype.js and then its core extensions (determined by filenames starting with “prototype”). Afterward, any additional scripts in the public/javascripts will be included in undefined order.

It is much preferable to use the javascript_include_tag helper method of AssetTagHelper to create remote SCRIPT links.

Escapes line breaks, single and double quotes for JavaScript segments.

Outputs a SCRIPT tag with the content inside. The html_options are added as tag attributes.

Returns a link that will trigger a JavaScript function using the onclick handler of the link. A return false; statement is added, so that the browser knows to stop processing the link click.

>> link_to_function "Greeting", "alert('Hello world!')"
=> <a onclick="alert('Hello world!'), return false;"
href="#">Greeting</a>

>> link_to_function(image_tag("delete"), "if (confirm('Really?'))
do_delete()")
>> <a onclick="if (confirm('Really?')) do_delete(); return false;"
href="#">
     <img src="/images/delete.png?" alt="Delete"/>
   </a>

Just like button_to_function, you can omit the function parameter and provide JavaScript RJS-style in a code block.

>> link_to_function("Show me more", nil, :id => "more_link") do |page|
     page[:details].visual_effect  :toggle_blind
     page[:more_link].replace_html "Show me less"
   end

>> <a href="#" id="more_link" onclick="try {
        $('details').visualEffect('toggle_blind'),
        $('more_link').update('Show me less'),
      }...

Alias for number_to_human_size.

Formats a number into a currency string. You can customize the format in the options hash.

>> number_to_currency(1234567890.50)
=> $1,234,567,890.50

>> number_to_currency(1234567890.506)
=> $1,234,567,890.51

>> number_to_currency(1234567890.506, :precision => 3)
=> $1,234,567,890.506

>> number_to_currency(1234567890.50, :unit => "£",
=> :separator => ",", :delimiter => ""
=> £1234567890,50

Formats the bytes in size into a more understandable representation. Useful for reporting file sizes to users. This method returns nil if size cannot be converted into a number. You can change the default precision of 1.

number_to_human_size(123)           => 123 Bytes
number_to_human_size(1234)          => 1.2 KB
number_to_human_size(12345)         => 12.1 KB
number_to_human_size(1234567)       => 1.2 MB
number_to_human_size(1234567890)    => 1.1 GB
number_to_human_size(1234567890123) => 1.1 TB
number_to_human_size(1234567, 2)    => 1.18 MB

This method is also aliased as human_size.

Formats a number as a percentage string. You can customize the format in the options hash.

number_to_percentage(100)    => 100.000%
number_to_percentage(100, {:precision => 0})   => 100%
number_to_percentage(302.0574, {:precision => 2})   => 302.06%

Formats a number as a U.S. phone number. You can customize the format in the options hash.

number_to_phone(1235551234)   => 123-555-1234
number_to_phone(1235551234, :area_code => true)   => (123) 555-1234
number_to_phone(1235551234, :delimiter => " ")    => 123 555 1234

Formats a number with grouped thousands using a delimiter. You can customize the format using optional delimiter and separator parameters.

number_with_delimiter(12345678)      => 12,345,678
number_with_delimiter(12345678.05)   => 12,345,678.05
number_with_delimiter(12345678, ".")   => 12.345.678

Formats a number with the specified level of precision. The default level of precision is 3.

number_with_precision(111.2345)    => 111.235
number_with_precision(111.2345, 2) => 111.24

This plugin,^[4] written by the guys behind the popular ERR the blog, is the pagination library of choice for most savvy Rails developers. Install it as a plugin using the following command:

$ script/plugin install svn://errtheblog.com/svn/plugins/will_paginate

In a nutshell, will_paginate works by adding a paginate class method to your ActiveRecord models that takes the place of find. In addition to find’s usual naming conventions, arguments, and options, it takes a :page parameter, for obvious reasons.

A query in the controller might look like this:

@posts = Post.paginate_by_board_id @board.id, :page => params[:page]

View template code is not impacted very much; it just gets fewer records to display. To render the pagination control, you just have to call will_paginate with the collection being rendered:

<%= will_paginate @posts %>

The plugin authors even give you a batch of CSS code so that you can make the pagination control look really pretty, as shown in Figure 11.1.

Figure 11.1. Pagination control formatted by CSS code

Users with search-engine optimization (SEO) concerns probably should go with will_paginate because it generates those individually numbered page links. Search robots see them as unique links and will keep clicking through and indexing their content. Conventional SEO wisdom is that search robots click next links only a few times before getting bored and moving on to more interesting sites.

This project,^[5] by notable Rails expert Bruce Williams, is hosted on Rubyforge and might appeal to some because of its simplicity. It’s a Rubygem, not a plugin, so you would type sudo gem install paginator to get your hands on it.

Instead of integrating tightly with ActiveRecord, the way that will_paginate does, the paginator library provides a neat little API to wrap the find invocation in your controller, as follows:

def index
  @pager = ::Paginator.new(Foo.count, PER_PAGE) do |offset, per_page|
    Foo.find(:all, :limit => per_page, :offset => offset)
  end
  @page = @pager.page(params[:page])
  ...
end

The view code, instead of relying on special helper methods, has the @page object at its disposal:

<% @page.items.each do |foo| %>
  <%# Show something for each item %>
<% end %>
<%= @page.number %>
<%= link_to("Prev", foos_url(:page => @page.prev.number)) if @page.prev? %>
<%= link_to("Next", foos_url(:page => @page.next.number)) [email protected]? %>

If you’re adventurous, check out http://svn.cardboardrocket.com/paginating_find for a simple pagination library that extends ActiveRecord’s find method, instead of trying to replace it. As a project, I think it’s much less mature than will_paginate or paginator, but looks promising.

The DOM class convention is to use the singular form of an object or class.

dom_class(post)   # => "post"
dom_class(Person) # => "person"

If you need to address multiple instances of the same class in the same view, you can prefix the dom_class:

dom_class(post, :edit)   # => "edit_post"
dom_class(Person, :edit) # => "edit_person"

The DOM class convention is to use the singular form of an object or class with the id following an underscore. If no id is found, prefix with new_ instead.

dom_class(Post.new(:id => 45)) # => "post_45"
dom_class(Post.new)            # => "new_post"

If you need to address multiple instances of the same class in the same view, you can prefix the dom_id like this: dom_class(Post.new(:id => 45), :edit) results in edit_post_45.

Returns plural/singular for a record or class, which is very useful for automatically rendering partial templates by convention.

partial_path(post)   # => "posts/post"
partial_path(Person) # => "people/person"

This helper method creates an HTML element with id and class parameters that relate to the specified ActiveRecord object.

For instance, assuming @person is an instance of a Person class, with an id value of 123 the following template code...

<% content_tag_for(:tr, @person) do %>
  <td><%=h @person.first_name %></td>
  <td><%=h @person.last_name %></td>
<% end %>

will produce the following HTML:

<tr id="person_123" class="person">
  ...
</tr>

If you require the HTML id attribute to have a prefix, you can specify it as a third argument:

>> content_tag_for(:tr, @person, :foo) do ...
=> <tr id="foo_person_123" class="person">...

The content_tag_for helper also accepts a hash of options, which will be converted to additional HTML attributes on the tag. If you specify a :class value, it will be combined with the default class name for your object instead of replacing it (since replacing it would defeat the purpose of the method!).

>> content_tag_for(:tr, @person, :foo, :class => 'highlight') do ...
=> <tr id="foo_person_123" class="person highlight">...

Produces a wrapper DIV element with id and class parameters that relate to the specified ActiveRecord object. This method is exactly like content_tag_for except that it’s hard-coded to output DIV elements.

Returns a CDATA section wrapping the given content. CDATA sections are used to escape blocks of text containing characters that would otherwise be recognized as markup. CDATA sections begin with the string <![CDATA[ and end with (and may not contain) the string ]]>.

Returns an HTML block tag of type name surrounding the content. Add HTML attributes by passing an attributes hash as options. Instead of passing the content as an argument, you can also use a block to hold additional markup (and/or additional calls to content_tag) in which case, you pass your options as the second parameter.

Here are some simple examples of using content_tag without a block:

>> content_tag(:p, "Hello world!")
=> <p>Hello world!</p>

>> content_tag(:div, content_tag(:p, "Hello!"), :class => "message")
=> <div class="message"><p>Hello!</p></div>

>> content_tag("select", options, :multiple => true)
=> <select multiple="multiple">...options...</select>

Here it is with content in a block (shown as template code rather than in the console):

<% content_tag :div, :class => "strong" do -%>
  Hello world!
<% end -%>

The preceding code produces the following HTML:

<div class="strong"><p>Hello world!</p></div>

Returns an escaped version of HTML without affecting existing escaped entities.

>> escape_once("1 > 2 & 3")
=> "1 < 2 & 3"

>> escape_once("<< Accept & Checkout")
=> "<< Accept & Checkout"

Returns an empty HTML tag of type name, which by default is XHTML compliant. Setting open to true will create an open tag compatible with HTML 4.0 and below. Add HTML attributes by passing an attributes hash to options.

The options hash is used with attributes with no value like (disabled and readonly), which you can give a value of true in the options hash. You can use symbols or strings for the attribute names.

>> tag("br")
=> <br />

>> tag("br", nil, true)
=> <br>

>> tag("input", { :type => 'text', :disabled => true })
=> <input type="text" disabled="disabled" />

>> tag("img", { :src => "open.png" })
=> <img src="open.png" />

Turns all URLs and e-mail addresses inside the text string into clickable links. The link parameter is used to optionally limit what should be linked; pass it :email_addresses or :urls. You can add HTML attributes to the generated links using href_options.

If for whatever reason you are unhappy with the way that Rails is turning your e-mail addresses and URLs into links, you can supply a block to this method. Each address found is yielded and the return value of the block is used as the link text.

>> auto_link("Go to http://obiefernandez.com and say hello to
[email protected]")
=> "Go to <a
href="http://www.rubyonrails.org">http://www.rubyonrails.org</a> and
say hello to <a
href="mailto:[email protected]">[email protected]</a>"

>> auto_link("Welcome to my new blog at http://www.myblog.com/.  Please
e-mail me at [email protected].", :all, :target => '_blank') do |text|
    truncate(text, 15)
  end
=> "Welcome to my new blog at <a href="http://www.myblog.com/"
target="_blank">http://www.m...</a>.
        Please e-mail me at <a
href="mailto:[email protected]">[email protected]</a>."

The preferred method of outputting text in your views is to use the <%= expression %> ERB syntax. The regular puts and print methods do not operate as expected in an eRuby code block; that is, if you expected them to output to the browser. If you absolutely must output text within a non-output code block like <% expression %>, you can use the concat method. I’ve found that this method can be especially useful in your own custom helper method implementations.

Creates a Cycle object whose to_s method cycles through elements of the array of values passed to it, every time it is called. This can be used, for example, to alternate classes for table rows.

Here’s an example that alternates CSS classes for even and odd numbers, assuming that the @items variable holds an array with 1 through 4:

<table>
 <% @items.each do |item| %>
   <tr class="<%= cycle("even", "odd") -%>">
    <td>item</td>
   </tr>
 <% end %>
</table>

As you can tell from the example, you don’t have to store the reference to the cycle in a local variable or anything like that; you just call the cycle method repeatedly. That’s convenient, but it means that nested cycles need an identifier. The solution is to pass cycle a :name => cycle_name option as its last parameter. Also, you can manually reset a cycle by calling reset_cycle and passing it the name of the cycle to reset.

For example, here is some data to iterate over:

# Cycle CSS classes for rows, and text colors for values within each
row
@items = [{:first => 'Robert', :middle => 'Daniel', :last => 'James'},
          {:first => 'Emily', :last => 'Hicks'},
          {:first => 'June', :middle => 'Dae', :last => 'Jones'}]

And here is the template code. Since the number of cells rendered varies, we want to make sure to reset the colors cycle before looping:

<% @items.each do |item| %>
<tr class="<%= cycle("even", "odd", :name => "row_class")
  <% item.values.each do |value| %>
    <td style="color:<%= cycle("red", "green", :name => "colors") -%>">
    <%= value %>
    </td>
  <% end %>
  <% reset_cycle("colors") %>
</tr>
<% end %>

Extracts an excerpt from text that matches the first instance of phrase. The radius expands the excerpt on each side of the first occurrence of phrase by the number of characters defined in radius (which defaults to 100). If the excerpt radius overflows the beginning or end of the text, the excerpt_string will be prepended/appended accordingly. If the phrase isn’t found, nil is returned.

>> excerpt('This is an example', 'an', 5)
=> "...s is an examp..."

>> excerpt('This is an example', 'is', 5)
=> "This is an..."

>> excerpt('This is an example', 'is')
=> "This is an example"

>> excerpt('This next thing is an example', 'ex', 2)
=> "...next t..."

>> excerpt('This is also an example', 'an', 8, '<chop> ')
=> "<chop> is also an example"

Highlights one or more phrases everywhere in text by inserting it into a highlighter string. The highlighter can be specialized by passing highlighter as a single-quoted string with 1 where the phrase is to be inserted.

>> highlight('You searched for: rails', 'rails')
=> You searched for: <strong class="highlight">rails</strong>

>> highlight('You searched for: ruby, rails, dhh', 'actionpack')
=> You searched for: ruby, rails, dhh

>> highlight('You searched for: rails', ['for', 'rails'],
'<em>1</em>')
=> You searched <em>for</em>: <em>rails</em>

>> highlight('You searched for: rails', 'rails', "<a
href='search?q=1'>1</a>")
=> You searched for: <a href='search?q=rails>rails</a>

Returns the text with all the Markdown codes turned into HTML tags. This method is only available if the BlueCloth gem is available.

>> markdown("We are using __Markdown__ now!")
=> "<p>We are using <strong>Markdown</strong> now!</p>"

>> markdown("We like to _write_ `code`, not just _read_ it!")
=> "<p>We like to <em>write</em> <code>code</code>, not just
<em>read</em> it!</p>"

>> markdown("The [Markdown
website](http://daringfireball.net/projects/markdown/) has more
information.")
=> "<p>The <a
href="http://daringfireball.net/projects/markdown/">Markdown
website</a> has more information.</p>"

>> markdown('![The ROR logo](http://rubyonrails.com/images/rails.png
"Ruby on Rails")')
=> '<p><img src="http://rubyonrails.com/images/rails.png" alt="The ROR
logo" title="Ruby on Rails" /></p>'

Attempts to pluralize the singular word unless count is 1. If the plural is supplied, it will use that when count is > 1. If the ActiveSupport Inflector is loaded, it will use the Inflector to determine the plural form; otherwise, it will just add an “s” to the singular word.

>> pluralize(1, 'person')
=> "1 person"

>> pluralize(2, 'person')
=> "2 people"

>> pluralize(3, 'person', 'users')
=> "3 users"

>> pluralize(0, 'person')
=> "0 people"

Resets a cycle (see the cycle method in this module) so that it starts cycling from its first element the next time it is called. Pass in a name to reset a named cycle.

Sanitizes the HTML by converting <form> and <script> tags into regular text, and removing all “on*” (e.g., onClick) attributes so that arbitrary JavaScript cannot be executed. It also strips href and src attributes that start with "javascript:". You can modify what gets sanitized by defining VERBOTEN_TAGS and VERBOTEN_ATTRS before this module is loaded.

>> sanitize('<script> do_nasty_stuff() </script>')
=> &lt;script> do_nasty_stuff() &lt;/script>

>> sanitize('<a href="javascript: sucker();">Click here for $100</a>')
=> <a>Click here for $100</a>

>> sanitize('<a href="#" onClick="kill_all_humans();">Click
here!!!</a>')
=> <a href="#">Click here!!!</a>

>> sanitize('<img src="javascript:suckers_run_this();" />')
=> <img />

Returns text transformed into HTML using simple formatting rules. Two or more consecutive newlines ( ) are considered to denote a paragraph and thus are wrapped in P tags. One newline ( ) is considered to be a line break and a BR tag is appended. This method does not remove the newlines from the text.

Strips all link tags from text leaving just the link text.

>> strip_links('<a href="http://www.rubyonrails.org">Ruby on
Rails</a>')
=> Ruby on Rails

>> strip_links('Please e-mail me at <a
href="mailto:[email protected]">[email protected]</a>.')
=> Please e-mail me at [email protected].

strip_links('Blog: <a href="http://www.myblog.com/" class="nav"
target="_blank">Visit</a>.')
=> Blog: Visit

Strips all HTML tags from the HTML, including comments. This uses the html-scanner tokenizer and so its HTML parsing ability is limited by that of html-scanner.

>> strip_tags("Strip <i>these</i> tags!")
=> Strip these tags!

>> strip_tags("<b>Bold</b> no more!  <a href='more.html'>See more
here</a>...")
=> Bold no more!  See more here...

>> strip_tags("<div id='top-bar'>Welcome to my website!</div>")
=> Welcome to my website!

This method is only available if the RedCloth gem is available. It returns text with all the Textile codes turned into HTML tags. Learn more about Textile syntax at http://hobix.com/textile/.

>> textilize("*This is Textile!* Rejoice!")
=> "<p><strong>This is Textile!</strong>  Rejoice!</p>"

>> textilize("I _love_ ROR(Ruby on Rails)!")
=> "<p>I <em>love</em> <acronym title="Ruby on
Rails">ROR</acronym>!</p>"

>> textilize("h2. Textile makes markup -easy- simple!")
=> "<h2>Textile makes markup <del>easy</del> simple!</h2>"

>> textilize("Visit Rails website "here":http://www.rubyonrails.org/.)
=> "<p>Visit the Rails website <a
href="http://www.rubyonrails.org/">here</a>.</p>"

Returns the text with all the Textile codes turned into HTML tags, but without the bounding <p> tag that RedCloth adds.

If text is longer than length, text will be truncated to the length specified and the last three characters will be replaced with the truncate_string:

>> truncate("Once upon a time in a world far far away", 4)
=> "Once..."

>> truncate("Once upon a time in a world far far away")
=> "Once upon a time in a world f..."

>> truncate("And they found that many people were sleeping better.",
15, "... (continued)")
=> "And they found... (continued)"

Wraps the text into lines no longer than line_width. This method breaks on the first whitespace character that does not exceed line_width (which is 80 by default).

>> word_wrap('Once upon a time', 4)
=> "Once
upon
a
time"

>> word_wrap('Once upon a time', 8)
=> "Once upon
a time"

>> word_wrap('Once upon a time')
=> "Once upon a time"

>> word_wrap('Once upon a time', 1)
=> "Once
upon
a
time"

Generates a form containing a single button that submits to the URL created by the set of options. This is the safest method to ensure that links that cause changes to your data are not triggered by search bots or accelerators. If the HTML button does not work with your layout, you can also consider using the link_to method (also in this module) with the :method modifier.

The options hash accepts the same options as the url_for method (also part of this module).

The generated FORM element has a class name of button-to to allow styling of the form itself and its children. The :method and :confirm options work just like the link_to helper. If no :method modifier is given, it defaults to performing a POST operation. You can also disable the button by passing :disabled => true.

>> button_to "New", :action => "new"
=> "<form method="post" action="/controller/new" class="button-to">
      <div><input value="New" type="submit" /></div>
    </form>"

>> button_to "Delete Image", { :action => "delete", :id => @image.id },
:confirm => "Are you sure?", :method => :delete
=>  "<form method="post" action="/images/delete/1" class="button-to">
       <div>
         <input type="hidden" name="_method" value="delete" />
         <input onclick="return confirm('Are you sure?'),"
value="Delete"
type="submit" />
       </div>
     </form>"

Returns true if the current request URI was generated by the given options. For example, let’s assume that we’re currently rendering the /shop/checkout action:

>> current_page?(:action => 'process')
=> false

>>current_page?(:action => 'checkout') # controller is implied
=> true

>> current_page?(:controller => 'shop', :action => 'checkout')
=> true

One of the fundamental helper methods. Creates a link tag of the given name using a URL created by the set of options. The valid options are covered in the description of this module’s url_for method. It’s also possible to pass a string instead of an options hash to get a link tag that uses the value of the string as the href for the link. If nil is passed as a name, the link itself will become the name.

Generally speaking, GET requests should be idempotent, that is, they do not modify the state of any resource on the server, and can be called one or many times without a problem. Requests that modify server-side resources or trigger dangerous actions like deleting a record should not usually be linked to with a normal hyperlink, since search bots and so-called browser accelerators can follow those links while spidering your site, leaving a trail of chaos.

If the user has JavaScript disabled, the request will always fall back to using GET, no matter what :method you have specified. This is accomplished by including a valid href attribute. If you are relying on the POST behavior, your controller code should check for it using the post?, delete?, or put? methods of request.

As usual, the html_options will accept a hash of HTML attributes for the link tag.

>> link_to "Visit Other Site", "http://www.rubyonrails.org/",
:confirm => "Are you sure?"
=> "<a href="http://www.rubyonrails.org/" onclick="return confirm('Are
you sure?'),">Visit Other Site</a>"

>> link_to "Help", { :action => "help" }, :popup => true
=> "<a href="/testing/help/" onclick="window.open(this.href);return
false;">Help</a>"

>> link_to "View Image", { :action => "view" }, :popup =>
['new_window_name', 'height=300,width=600']
=> "<a href="/testing/view/" onclick="window.open(this.href,
'new_window_name','height=300,width=600'),return false;">View
Image</a>"

>> link_to "Delete Image", { :action => "delete", :id => @image.id },
:confirm => "Are you sure?", :method => :delete
=> <a href="/testing/delete/9/" onclick="if (confirm('Are you sure?'))
{
var f = document.createElement('form'),
       f.style.display = 'none'; this.parentNode.appendChild(f);
f.method = 'POST'; f.action = this.href;
       var m = document.createElement('input'), m.setAttribute('type',
'hidden'), m.setAttribute('name', '_method'),
       m.setAttribute('value', 'delete'), f.appendChild(m);f.submit();
};return false;">Delete Image</a>

Creates a link tag using the same options as link_to if the condition is true; otherwise, only the name is output (or block is evaluated for an alternative value, if one is supplied).

Creates a link tag using the same options as link_to unless the condition is true, in which case only the name is output (or block is evaluated for an alternative value, if one is supplied).

Creates a link tag using the same options as link_to unless the condition is true, in which case only the name is output (or block is evaluated for an alternative value, if one is supplied).

This method is actually pretty useful sometimes. Remember that the block given to link_to_unless_current is evaluated if the current action is the action given. So, if we had a comments page and wanted to render a “Go Back” link instead of a link to the comments page, we could do something like this:

<%= link_to_unless_current("Comment", { :controller => 'comments',
    :action => 'new}) do
      link_to("Go back", { :controller => 'posts', :action => 'index'
})
    end %>

Creates a mailto link tag to the specified email_address, which is also used as the name of the link unless name is specified. Additional HTML attributes for the link can be passed in html_options.

The mail_to helper has several techniques for hindering e-mail harvesters and customizing the e-mail address itself by passing special keys to html_options:

Here are some examples of usages:

>> mail_to "[email protected]"
=> <a href="mailto:[email protected]">[email protected]</a>

>> mail_to "[email protected]", "My email", :encode => "javascript"
=> <script type="text/javascript">eval(unescape('%64%6f%63...%6d%65'))
</script>

>> mail_to "[email protected]", "My email", :encode => "hex"
=> <a href="mailto:%6d%65@%64%6f%6d%61%69%6e.%63%6f%6d">My email</a>

>> mail_to "[email protected]", nil, :replace_at => "_at_", :replace_dot =>
"_dot_", :class => "email"
=> <a href="mailto:[email protected]"
class="email">me_at_domain_dot_com</a>

>> mail_to "[email protected]", "My email", :cc => "[email protected]",
:subject => "This is an example email"
=> <a
href="mailto:[email protected][email protected]&subject=This%20i
s%20an%20example%20email">My email</a>

The url_for method returns a URL for the set of options provided and takes the same options as url_for in ActionController (discussed extensively in Chapter 3, “Routing”).

Note that by default, the :only_path option is set to true so that you’ll get the relative /controller/action instead of the fully qualified URL like http://example.com/controller/action.

When called from a view, url_for returns an HTML-escaped URL. If you need an unescaped URL, pass :escape => false in the options.

Here is the complete list of options accepted by url_for:

>> url_for(:action => 'index')
=> /blog/

>> url_for(:action => 'find', :controller => 'books')
=> /books/find

>> url_for(:action => 'login', :controller => 'members', :only_path =>
false, :protocol => 'https')
=> https://www.railsapplication.com/members/login/

>> url_for(:action => 'play', :anchor => 'player')
=> /messages/play/#player

>> url_for(:action => 'checkout', :anchor => 'tax&ship')
=> /testing/jump/#tax&ship

>> url_for(:action => 'checkout', :anchor => 'tax&ship', :escape =>
false)
=> /testing/jump/#tax&ship

If you pass an ActiveRecord or ActiveResource model instance instead of a hash to any method in the UrlModule that takes url_for parameters, you’ll trigger generation of a path for that record’s named route (assuming that one exists). The lookup is based on the name of the class and is smart enough to call new_record? on the passed model to figure out whether to reference a collection or member route.

For example, passing a Timesheet object will attempt to use the timesheet_path route. If that object’s route is nested within another route, you’ll have to use a path helper method explicitly, since Rails won’t be able to figure it out automatically.

>> url_for(Workshop.new)
=> /workshops

>> url_for(@workshop) # existing record
=> /workshops/5

Here is a simple helper method that has been of use to me on many projects now. It’s called page_title and it combines two simple functions essential to a good HTML document:

This helper assumes that you want the title and h1 elements of the page to be the same, and has a dependency on your application template. The code for the helper is in Listing 11.6 and would be added to app/helpers/application_helper.rb, since it is applicable to all views.

def page_title(name)
  @title = name
  content_tag("h1", name)
end

First it sets the value of a variable named @title and then it outputs an h1 element containing the same text. I could have used string interpolation on the second line, such as "<h1>#{name}</h1>", but in my opinion that would be sloppier than using the built-in Rails helper method content_tag.

My application template looks for a @page_title to be available, in which case it will prepend it to the site title, the name of the application:

<html>
  <head>
    <title><%= "#@page_title - " if @page_title %>Site Title</title>

As should be obvious, you call the page_title method in your view template where you want to have an h1 element:

<%= page_title "New User" %>
<%= error_messages_for :user %>
<% form_for(:user, :url => user_path) do |f| %>
  ...

Here’s another relatively simple helper. This time, instead of simply outputting data, we are encapsulating some view logic that decides whether to display a user’s profile photo or a placeholder image. It’s logic that you would otherwise have to repeat over and over again throughout your application.

The dependency (or contract) for this particular helper is that the user object being passed in has a profile_photo associated to it, which is an attachment model based on Rick Olson’s excellent attachment_fu Rails plugin.^[3] The code in Listing 11.7 should be easy enough to understand without delving into the details of attachment_fu. Since this is a code example, I broke out the logic for setting src into an if/else structure; otherwise, this would be a perfect place to use Ruby’s ternary operator.

def photo_for(user, size=:thumb)
  if user.profile_photo
    src = user.profile_photo.public_filename(size)
  else
    src = 'user_placeholder.png'
   end
   link_to(image_tag(src), user_path(user)
end

Lots of web applications feature user-interface concepts called breadcrumbs. They are made by creating a list of links, positioned near the top of the page, displaying how far the user has navigated into a hierarchically organized application. I think it makes sense to extract breadcrumb logic into its own helper method instead of leaving it in a layout template.

The trick to our example implementation (shown in Listing 11.8) is to use the presence of instance variables, based on a convention specific to your application, to determine whether or not to add elements to an array of breadcrumb links.

 1 def breadcrumbs
 2   return if controller.controller_name == 'homepage'

 3   html = [link_to('Home', home_path)]

 4   # first level
 5   html << link_to('Companies', companies_path) if @companies ||
     @company
 6   html << link_to(@company, company_path(@company)) if @company

 7   # second level
 8   html << link_to('Departments', departments_path) if @depts || @dept
 9   html << link_to(@dept, department_path(@dept)) if @dept

10   # third and final level
11   html << link_to('Employees', employees_path) if @employees ||
     @employee
12   html << link_to(@employee.name, employee_path(@employee)) if
     @employee

13   html.join(' &gt; ')
14 end

Here’s the line-by-line explanation of the code, noting where certain application-design assumptions are made:

On line 2, we abort execution if we’re in the context of the application’s homepage controller, since its pages don’t ever need breadcrumbs. A simple return with no value implicitly returns nil, which is fine for our purposes—nothing will be output to the layout template.

On line 3 we are starting to build an array of HTML links, held in the html local variable, which will ultimately hold the contents of our breadcrumb trail. The first link of the breadcrumb trail always points to the home page of the application, which of course will vary, but since it’s always there we use it to initialize the array. In this example, it uses a named route called home_path.

After the html array is initialized, all we have to do is check for the presence of the variables that make up the hierarchy (lines 4 to 12). It is assumed that if a department is being displayed, its parent company will also be in scope. If an employee is being displayed, both its department and company will be in scope as well. This is not just an arbitrary design choice—it is a common pattern in Rails applications that are modeled based on REST principles and using nested resource routes.

Finally, on line 13, the array of HTML links is joined with the > character, to give the entire string the traditional breadcrumb appearance.

Let’s trace the steps to writing a helper method that wraps what I consider to be a general-purpose partial. Listing 11.9 contains code for a partial for a piece of a user interface that is common to many applications, and generally referred to as a tile. It pairs a small thumbnail photo of something on the left side of the widget, with a linked name and description on the right.

Tiles can also represent other models in your application, such as users and files. As I mentioned, tiles are a very common construct in modern user interfaces and operating systems. So let’s take the cities tiles partial and transform it into something that can be used to display other types of data.

 1 <table class="cities tiles">
 2  <% cities.in_groups_of(columns) do |row| -%>
 3   <tr>
 4   <% row.each do |city| -%>
 5    <td id="<%= dom_id(city) %>">
 6     <div class="left">
 7      <%= image_tag city.main_photo.public_filename(:thumb) -%>
 8     </div>
 9     <div class="right">
10       <div class="title"><%= city.name %></div>
11       <div class="description"><%= city.description %></div>
12     </div>
13    </td>
14   <% end # row.each -%>
15   </tr>
16  <% end # in_groups_of -%>
17 </table>

render :partial => "cities/tiles",
       :locals => { :collection => @user.cities, :columns => 3 }

<% columns = 3 unless defined? columns %>

module CitiesHelper

  def tiled(cities, columns=3)
    render :partial => "cities/tiles",
           :locals => { :collection => cities, :columns => columns }
  end

end

Now that we’ve set the stage, the fun can begin. The first thing we’ll do is to move the helper method to the ApplicationHelper module so that it’s available to all view templates. We’ll also move the partial template file to app/views/shared/_tiled_table.html.erb to denote that it isn’t associated with a particular kind of view, and to more accurately convey its use. As a matter of good code style, I also do a sweep through the implementation and generalize the identifiers appropriately. The reference to cities becomes collection. The block variable item becomes item. Listing 11.11 has the new partial code.

 1 <table class="tiles">
 2  <% collection.in_groups_of(columns) do |row| -%>
 3   <tr>
 4   <% row.each do |item| -%>
 5    <td id="<%= dom_id(item) %>">
 6     <div class="left">
 7      <%= image_tag(item.main_photo.public_filename(:thumb)) %>
 8     </div>
 9     <div class="right">
10       <div class="title"><%= item.name %></div>
11       <div class="description"><%= item.description %></div>
12     </div>
13    </td>
14   <% end # row.each -%>
15   </tr>
16  <% end # in_groups_of -%>
17 </table>

There’s still the matter of a contract between this partial code and the objects that it is rendering. Namely, they must respond to the following messages: main_photo, name, and description. A survey of other models in my application reveals that I need more flexibility. Some things have names, but others have titles. Sometimes I want the description to appear under the name of the object represented, but other times I want to be able to insert additional data about the object plus some links.

 1     <div class="left">
 2       <%= link_to thumbnail.call(item), link.call(item) %>
 3     </div>
 4     <div class="right">
 5       <div class="title">
 6         <%= link_to title.call(item), link.call(item) %>
 7       </div>
 8       <div class="description"><%= description.call(item) %></div>
 9     </div>

 1  module ApplicationHelper

 2    def tiled(collection, opts={})
 3      raise 'link option is required' unless opts[:link]

 4      opts[:columns] ||= 3

 5      opts[:thumbnail] ||= lambda do |item|
 6        image_tag(item.photo.public_filename(:thumb))
 7       end

 8      opts[:title] ||= lambda {|item| item.to_s }
 9      opts[:description] ||= lambda {|item| item.description }

10      render :partial => "shared/tiled_table",
11             :locals => { :collection  => collection,
12                          :columns     => opts[:columns] || 3,
13                          :thumbnail   => opts[:thumbnail],
14                          :title       => opts[:title],
15                          :description => opts[:description] }
16    end
17  end

<%= tiled(@cities, :link => lambda {|city| city_path(city)}) %>