https://github.com/jbox-web/page_title_helper
https://github.com/jbox-web/page_title_helper
Last synced: 8 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/jbox-web/page_title_helper
- Owner: jbox-web
- License: mit
- Created: 2025-09-23T09:36:08.000Z (9 months ago)
- Default Branch: master
- Last Pushed: 2025-09-23T17:38:02.000Z (9 months ago)
- Last Synced: 2025-09-23T19:14:50.058Z (9 months ago)
- Language: Ruby
- Size: 237 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# Page title helper
[](https://github.com/jbox-web/page_title_helper/blob/master/LICENSE)
[](https://github.com/jbox-web/page_title_helper/actions)
[](https://qlty.sh/gh/jbox-web/projects/page_title_helper)
[](https://qlty.sh/gh/jbox-web/projects/page_title_helper)
This project adheres to [Semantic Versioning](https://semver.org/).
## What does this gem do?
Ever wondered if there was an easier and DRY-way to set your page titles
(and/or headings), introducing _page title helper_, a small view helper for
Rails to inflect titles from controllers and actions.
In your layout, add this to your ``-section:
```html
<%= page_title %>
```
That's it. Now just add translations, in e.g. `config/locales/en.yml`:
```yaml
en:
contacts:
index:
title: "Contacts"
```
When `/contacts/` is requested, the key `:en, :contacts, :index, :title`
is looked up and printed, together with the applications basename, like:
`Contacts - My cool App`.
The format etc. is of course configurable, just head down to the options.
## Installation
Put this in your `Gemfile` :
```ruby
git_source(:github){ |repo_name| "https://github.com/#{repo_name}.git" }
gem 'page_title_helper', github: 'jbox-web/page_title_helper'
```
then run `bundle install`.
## Translated titles
All translated titles are inflected from the current controller and action,
so to easily explain all lookups, here an example with the corresponding
lookups:
```
Admin::AccountController#index => :'admin.account.index.title'
:'admin.account.title'
options[:default]
```
For `create` and `update` a further fallback to `new.title` and `edit.title`
have been added, because they certainly are duplicates.
## Customize titles
Need a custom title, or need to fill in some placeholders? Just use the _bang_
method (`page_title!`), in e.g. `contacts/show.html.erb` the requirement is to
display the contacts name in the `-tag`as well as in the heading?
```html
<%= page_title!(@contact.name) %>
```
A call to `page_title` will now return the contacts name, neat :) if for
example the `
` does not match the ``, then well, just do something
like:
```html
<% page_title!(@contact.name + " (" + @contact.company.name + ")") %>
<%= @contact.name %>
```
Guess, that's it. Of course it's also possible to use `translate` within
`page_title!`, to translate custom titles, like:
In `config/locales/en.yml`:
```yaml
en:
dashboard:
index:
title: "Welcome back, {{name}}"
```
In `app/views/dashboard/index.html.erb`:
```html
<%= page_title!(t('.title', name: @user.first_name)) %>
```
## More fun with :format
The `:format` option is used to specify how a title is formatted, i.e. if the
app name is prepended or appended or if it contains the account name etc.
It uses a similar approach as paperclip's path interpolations:
```ruby
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:
```ruby
PageTitleHelper.interpolates :controller do |env|
env[:view].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:
```ruby
page_title! "untitled"
page_title format: false # => "untitled"
```
Need a custom format for a single title? Just return an array:
In the view:
```html
<%= page_title!(@contact.name, ":title from :company - :app") %>
# => Franz Meyer
```
In the ``:
```html
<%= page_title %> # => this time it will use custom title like "Franz Meyer from ABC Corp. - My cool app"
```
To streamline that feature a bit and simplify reuse of often used formats,
it's possible to define format aliases like:
In an initializer, e.g., `config/initializers/page_title_helper.rb`:
```ruby
PageTitleHelper.formats[:with_company] = ":title from :company - :app"
# show app first for promo pages :)
PageTitleHelper.formats[:promo] = ":app - :title"
```
Then in the view to display a contact:
```ruby
page_title! @contact.name, :with_company
```
Or for the promo page via `config/locales/en.yml` (!):
```yaml
en:
pages:
features:
title:
- "Features comparison"
- !ruby/sym promo
```
Pretty, cool, ain't it? The special `format: :app` works also via the `formats`
hash. Then there is also a `:default` format, which can be used to override the
default format.
## All options - explained
| Option | Description | Default | Values |
|----------|-------------|---------|--------|
|`:app` | Specify the applications name, however it's recommended to define it via translation key `:'app.name'`. | Inflected from `Rails.root`| string |
|`: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.translate`'s `:default` option. | `'app.tagline'` | string, symbol or array of those |
|`:format` | Defines the output format, accepts a string containing multiple interpolations, or a symbol to a format alias, see _More fun with `:format`_. If set to `false`, just the current title is returned. | `:default`| string, symbol |
Options can be set globally via `PageTitleHelper.options`. Note, currently it
only makes sense to set `:default` globally.
To add or change formats use:
```ruby
# change the default format used (if no format is specified):
PageTitleHelper.formats[:default] = ":title // :app"
# add a custom format alias (which can be used with page_title(format: :promo))
PageTitleHelper.formats[:promo] = ":app // :title"
```
_Note:_ It's recommended to add this kind of stuff to an initializer, like e.g.
`config/initializers/page_title_helper.rb`.
## A (maybe useful) interpolation
The internationalized controller name, with fallback to just display the
humanized name:
```ruby
PageTitleHelper.interpolates :controller do |env|
c = env[:view].controller
I18n.t(c.controller_path.tr('/', '.') + '.controller', default: c.controller_name.humanize)
end
```
_Note:_ Put this kind of stuff into an initializer, like
`config/initializers/page_title_helper.rb` or something like that.
## Licence and copyright
Copyright (c) 2009 Lukas Westermann (Zurich, Switzerland), released under the MIT license