lwe-page_title_helper

= 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 -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 -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 (c) 2009 Lukas Westermann (Zurich, Switzerland), released under the MIT license