Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 121 lines (73 sloc) 3.127 kb
3a64d92 @mokolabs switching README to markdown
mokolabs authored
1 Headliner
2 =========
3
ed34249 @mokolabs switching README to markdown
mokolabs authored
4 Headliner is a Rails plugin that makes it easier to assign and format page titles from your views.
3a64d92 @mokolabs switching README to markdown
mokolabs authored
5
6
7 Background
8 ==========
9
10 Normally, if your Rails application has lots of actions and a shared layout, you might find yourself setting custom page title names in your controllers.
11
12 Here's an example:
13
14 class PagesController < ApplicationController
15 def about
16 @title = "About us"
17 end
18 end
19
20 Then, in your main layout, you might have something like this:
21
22 <head>
23 <title>My website<% if @title %>: <%= @title %><% end %></title>
24 </head
25
26 This works okay... but page titles don't really belong in controllers, do they?
27
28 So, by moving these titles into your views, we can DRY things up a bit and reinforce the MVC design pattern that's so fundamental to Ruby on Rails.
29
30
cbc569c @mokolabs switching README to markdown
mokolabs authored
31 Install
32 =======
33
34 To install, just add Headliner to your `vendor/plugins` directory:
35
36 script/plugin install git://github.com/mokolabs/headliner.git
37
38
3a64d92 @mokolabs switching README to markdown
mokolabs authored
39 Usage
40 =====
41
42 First, add this code to your main layout:
43
44 <head>
45 <%= title :site => "My website" %>
46 </head>
47
48 Then, to set the page title, add this to each of your views:
49
50 <h1><%= title "My page title" %></h1>
51
52 When views are rendered, the page title will be included in the right
53 spots:
54
55 <head>
56 <title>My website | My page title</title>
57 </head>
58 <body>
59 <h1>My page title</h1>
60 </body>
61
62
63 Options
64 =======
65
66 Use these options to customize the title format:
67
926492e @mokolabs switching README to markdown
mokolabs authored
68 :prefix (text between site name and separator)
69 :separator (text used to separate website name from page title)
70 :suffix (text between separator and page title)
71 :lowercase (when true, the page name will be lowercase)
72 :reverse (when true, the page and site names will be reversed)
73 :default (default title to use when title is blank)
3a64d92 @mokolabs switching README to markdown
mokolabs authored
74
75 And here are a few examples to give you ideas.
76
77 <%= title :separator => "&mdash;" %>
78 <%= title :prefix => false, :separator => ":" %>
79 <%= title :lowercase => true %>
80 <%= title :reverse => true, :prefix => false %>
81 <%= title :default => "The ultimate site for Rails" %>
82
83
84 Dealing with special pages
85 ==========================
86
87 How do you set the page title without showing it in the view?
88
89 <% title "My page title" %>
90
91 What if your view headline is different from your page title?
92
93 <%= title "My page title", "My headline" %>
94
95
96 Mr. T says, ‘Use my method, fool!’
97 ==================================
98
99 Just like ERB's HTML safe method, you can invoke Headliner with a single
100 letter alias.
101
102 <h1><%=t "My page title" %></h1>
103
104
105 How does it work?
106 =================
107
108 Ruby on Rails renders actions *before* inserting them into layouts. So, if you set a variable in your view, it will be accessible in your layout. But, at first glance, it looks like you're using a variable (in the head) before it's been assigned a value (in the body). Cool, huh?
109
110
111 Contributors
112 ============
113
114 Special thanks to James Chan, Nick Zadrozny, and Jordan Fowler.
115
116
117 Feedback
118 ========
119
72fa6cc @mokolabs updated README feedback link
mokolabs authored
120 Comments and patches welcome at [http://github.com/mokolabs/headliner/](http://github.com/mokolabs/headliner/).
Something went wrong with that request. Please try again.