Page title helper

Ever wondered if there was an easier and DRY-way to set your page titles (and/or headings). Backed by Rails (only tested on 2.3.x) and it’s new I18n-class the solution is a simple helper method.

In your layout add this to your <head>-section:

...
<title><%=h page_title %></title>
...

That’s it. Now just add your translations, to the locales, in e.g. config/locales/en.yml:

en:
  contacts:
    index:
      title: "Contacts"

When contacs/index.html.erb is rendered, the key :en, :contacts, :index, :title is looked up and printed, together with the applications basename, like: My cool app - Contacts. The format etc. is of course configurable, just head down to the options.

Customize titles

Need a custom title, or need to fill in some placeholders? Just provide a block, in e.g. contacts/show.html.erb the requirement is to display the contacts name in the <title>-tag as well as in the heading?

<h1><%=h page_title { @contact.name } %></h1>

A call to page_title will now return the contacts name, neat :) if for example the h1 does not match the title, then well, just do something like:

<% page_title { @contact.name + " (" + @contact.company.name + ")" } %>
<h1><%=h @contact.name %></h1>

Guess, that’s it. Of course it’s also possible to use translate within the page_title block, so to translate customzied titles, like:

# in config/locales/en.yml:
en:
  dashboard:
    index:
      title: "Welcome back, {{name}}"

# in app/views/dashboard/index.html.erb:
<h1><%=h page_title { t '.title', :name => @user.first_name } %></h1>

Btw - a helpful rule-of-thumb: if page_title is used with a block a title is defined, if it’s used without the current title is rendered.

More fun with :format

The :format option is used to specify how a title is formatted, i.e. if the app name is prependor appended, or if it contains the account name etc. It uses a similar approach as paperclips path interpolations:

page_title :format => ':title / :app' # => "Contacts / My cool app"

Adding custom interpolations is as easy as defining a block, for example to access the current controller:

PageTitleHelper.interpolates :controller do |env|
  env.controller.controller_name.humanize
end

page_title :format => ':title / :controller / :app' # => "Welcome back / Dashboard / My cool app"

To access just the title, without any magic app stuff interpolated or appended, use:

page_title { "untitled" }
page_title :format => false # => "untitled"

All options - explained

  • page_title { ... } - not per se an option, but if a block is given the methods sets a custom title and overwrites any DRY-I18n title.

  • :app - specifiy the applications name, however it’s recommended to define the translation key :'app.name' or use the the fallback behaviour for the humanzied basename of RAILS_ROOT.

  • :default - string which is displayed when no translation exists and no custom title has been specified. Can also be set to a symbol or array to take advantage of I18n.translates :default option. (Default is :'app.tagline')

  • :format - defines the output format, accepts a string containing multiple interpolations, see More fun with :format. If set to false, just the current title is returned. If :format => :app then just the application name is returned. (Default is ":app - :title")

  • :suffix - not happy with the fact that the translations must be named like en -> contacts -> index -> title, but prefer e.g. them to be suffixed with page_title? Then just set :suffix => :page_title. (Default :title)

If an option should be set globally it’s possible to change the default options hash as follows:

PageTitleHelper.options[:format] = ':title / :app'

Note, currently it only makes sense to set :format and/or :default globally.

Some (maybe useful) interpolations

The internationalized controller name, with fallback to just display the humanized name:

PageTitleHelper.interpolates :controller do |env|
  I18n.t env.controller.controller_path.tr('/','.') + '.controller', :default => env.controller.controller_name.humanize
end

Note: Where should I put these, as well as the default options? I’d put them in a new file at config/initializers/page_title.rb or someting like that.

Licence and copyright

Copyright © 2009 Lukas Westermann (Zurich, Switzerland), released under the MIT license