-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathtwitter-bootstrap-rails.html
311 lines (301 loc) · 20.9 KB
/
twitter-bootstrap-rails.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
<!DOCTYPE html>
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8"/>
<title>Twitter Bootstrap and Rails</title>
<link href="https://plus.google.com/u/0/b/117374718581973393536/117374718581973393536/posts/" rel="publisher" />
<link rel="stylesheet" href="/css/bootstrap.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/screen.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/gollum.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/site.css" type="text/css" charset="utf-8" />
<link rel="stylesheet" href="/css/syntax.css" type="text/css" charset="utf-8" />
<script src="http://code.jquery.com/jquery-1.6.min.js" type="text/javascript"></script>
<script src="/javascript/jquery.text_selection-1.0.0.min.js" type="text/javascript"></script>
<script src="/javascript/jquery.previewable_comment_form.js" type="text/javascript"></script>
<script src="/javascript/jquery.tabs.js" type="text/javascript"></script>
<script src="/javascript/gollum.js" type="text/javascript"></script>
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-5109366-14']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="navbar navbar-fixed-top">
<div class="navbar-inner">
<div class="container">
<a href="/" class="brand">RailsApps Project</a>
<ul class="pull-right nav">
<li><a href="http://blog.railsapps.org/" class="twitter">Blog</a></li>
<li><a href="http://twitter.com/rails_apps" class="twitter">Twitter</a></li>
<li><a href="https://plus.google.com/117374718581973393536" class="google">Google +</a></li>
<li><a href="https://github.com/RailsApps" class="github">GitHub Repository</a></li>
</ul>
</div>
</div>
</div>
<div class="container">
<div class="page-header">
<h1>Twitter Bootstrap and Rails</h1>
</div>
<div class="content wikistyle gollum textile">
<h1>Twitter Bootstrap and Rails</h1>
<h4>by Daniel Kehoe</h4>
<p><em>Last updated 23 April 2012</em></p>
<p>Twitter Bootstrap and Rails. Shows how to set up a Rails 3.2 application to use Twitter Bootstrap as a <span class="caps">CSS</span> front-end framework, providing an HTML5 application layout and <span class="caps">CSS</span> styling for Rails alerts and notices.</p>
<p>You can use Twitter Bootstrap to quickly add attractive <span class="caps">CSS</span> styling to your application. <a href="http://twitter.github.com/bootstrap/">Twitter Bootstrap</a> and other <span class="caps">CSS</span> front-end frameworks (such as <a href="http://foundation.zurb.com/">Zurb Foundation</a>) are toolkits that provide the kind of structure and convention that make Rails popular for server-side (“back-end”) development. Twitter Bootstrap is the most popular of the various <span class="caps">CSS</span> front-end frameworks.</p>
<p>This is a guide for developers using the example apps from the <a href="http://railsapps.github.com/">Rails Apps</a> repository. Others may find it helpful as well. It’s easy to use an application template from the <a href="https://github.com/RailsApps/rails3-application-templates">RailsApps Application Templates</a> repository to install Twitter Bootstrap and set up your default application layout. If you do so, the script will offer to install Twitter Bootstrap or other <span class="caps">CSS</span> front-end frameworks and set up your default application layout accordingly. An example app and <a href="http://railsapps.github.com/tutorial-rails-bootstrap-devise-cancan.html">Rails tutorial for Devise with CanCan and Twitter Bootstrap</a> gives an example of a complete working application offering user authentication and administrative authorization combined with Twitter Bootstrap.</p>
<h2>Installing Twitter Bootstrap</h2>
<p>There are four steps to adding Twitter Bootstrap to a Rails application:</p>
<ul>
<li>add a gem to the <strong>Gemfile</strong>
</li>
<li>modify the file <strong>app/assets/javascripts/application.js</strong> to add Bootstrap’s Javascript files</li>
<li>add the file <strong>app/assets/stylesheets/bootstrap_and_overrides.css.scss</strong> to add Bootstrap’s <span class="caps">CSS</span> files</li>
<li>modify the file <strong>app/views/layouts/application.html.erb</strong> to change the application layout</li>
<li>include Twitter Bootstrap <span class="caps">CSS</span> styling in Rails flash messages</li>
</ul><p>You’ll find full instructions below.</p>
<h3>Twitter Bootstrap Gem</h3>
<p>Several options are available for installing Twitter Bootstrap in a Rails application. Twitter Bootstrap can be installed using either its native <a href="http://lesscss.org/"><span class="caps">LESS</span> <span class="caps">CSS</span></a> language or the <a href="http://sass-lang.com/"><span class="caps">SASS</span></a> language. See the article <a href="http://rubysource.com/twitter-bootstrap-less-and-sass-understanding-your-options-for-rails-3-1/">Twitter Bootstrap, Less, and Sass: Understanding Your Options for Rails 3.1</a>. <span class="caps">SASS</span> is a default for <span class="caps">CSS</span> development in Rails so I recommend installing Thomas McDonald’s <a href="https://github.com/thomas-mcdonald/bootstrap-sass">bootstrap-sass</a> gem.</p>
<p>In your <strong>Gemfile</strong>, add:</p>
<pre>
gem 'bootstrap-sass'
</pre>
<p>and run <code>$ bundle install</code>.</p>
<h3>Include the Twitter Bootstrap Javascript</h3>
<p>Include the Twitter Bootstrap Javascript files by modifying the file <strong>app/assets/javascripts/application.js</strong>:</p>
<pre>
//= require jquery
//= require jquery_ujs
//= require bootstrap
//= require_tree .
</pre>
<h3>Using <span class="caps">SASS</span>
</h3>
<p>The <a href="http://sass-lang.com/"><span class="caps">SASS</span></a> language is the default for <span class="caps">CSS</span> development in Rails.</p>
<p>It’s a good idea to rename the <strong>app/assets/stylesheets/application.css</strong> file as <strong>app/assets/stylesheets/application.css.scss</strong>.</p>
<p>This will allow you to use the advantages of the <span class="caps">SASS</span> syntax and features for your application stylesheet. For more on the advantages of <span class="caps">SASS</span> and how to use it, see the <a href="http://railscasts.com/episodes/268-sass-basics"><span class="caps">SASS</span> Basics</a> RailsCast from Ryan Bates.</p>
<h3>Import the Twitter Bootstrap <span class="caps">CSS</span>
</h3>
<p>Next, import the Twitter Bootstrap <span class="caps">CSS</span> files. You can modify the <strong>app/assets/stylesheets/application.css.scss</strong> file to import Bootstrap. However, I recommend adding a new file <strong>app/assets/stylesheets/bootstrap_and_overrides.css.scss</strong> file. You may wish to modify the Twitter Bootstrap <span class="caps">CSS</span> rules; you can do so in the <strong>application.css.scss</strong> file but placing changes to Twitter Bootstrap <span class="caps">CSS</span> rules in the <strong>bootstrap_and_overrides.css.scss</strong> file will keep your <span class="caps">CSS</span> better organized.</p>
<p>The file <strong>app/assets/stylesheets/bootstrap_and_overrides.css.scss</strong> is automatically included and compiled into your Rails application.css file by the <code>*= require_tree .</code> statement in the <strong>app/assets/stylesheets/application.css.scss</strong> file.</p>
<p>Add the file <strong>app/assets/stylesheets/bootstrap_and_overrides.css.scss</strong>:</p>
<pre>
// Set the correct sprite paths
$iconSpritePath: image-path('glyphicons-halflings.png');
$iconWhiteSpritePath: image-path('glyphicons-halflings-white.png');
@import "bootstrap";
body { padding-top: 60px; }
@import "bootstrap-responsive";
</pre>
<p>The file will import both basic Bootstrap <span class="caps">CSS</span> rules and the Bootstrap rules for responsive design (allowing the layout to resize for various devices and secreen sizes).</p>
<p>The <span class="caps">CSS</span> rule <code>body { padding-top: 60px; }</code> applies an additional <span class="caps">CSS</span> rule to accommodate the “Bootstrap black bar” heading created by the <code>navbar-fixed-top class</code> in the <code>header</code> tag in the layout below.</p>
<p>Finally, to provide an example of adding a <span class="caps">CSS</span> rule that will be used on every page of your application, the following code creates a nice gray box as a background to page content.</p>
<p>Add this to your <strong>app/assets/stylesheets/application.css.scss</strong> file for a gray background:</p>
<pre>
.content {
background-color: #eee;
padding: 20px;
margin: 0 -20px; /* negative indent the amount of the padding to maintain the grid system */
-webkit-border-radius: 0 0 6px 6px;
-moz-border-radius: 0 0 6px 6px;
border-radius: 0 0 6px 6px;
-webkit-box-shadow: 0 1px 2px rgba(0,0,0,.15);
-moz-box-shadow: 0 1px 2px rgba(0,0,0,.15);
box-shadow: 0 1px 2px rgba(0,0,0,.15);
}
</pre>
<h2>Default Application Layout</h2>
<p>Generating a new Rails application with the <code>rails new</code> command will create a default application layout. Rails will use the layout defined in the file <strong>app/views/layouts/application.html.erb</strong> as a default for rendering any page. If you are using Haml, the file will be <strong>app/views/layouts/application.html.haml</strong>.</p>
<p>You’ll want to add navigation links, include flash messages for errors and notifications, and apply <span class="caps">CSS</span> styling using Twitter Bootstrap.</p>
<p>See the article <a href="http://railsapps.github.com/rails-html5-boilerplate.html">HTML5 Boilerplate for Rails Developers</a> for an explanation of what should be included in the default application layout.</p>
<h3>Default Application Layout with Twitter Bootstrap (<span class="caps">ERB</span>)</h3>
<p>Twitter Bootstrap provides additional elements for a more complex page layout.</p>
<p>Replace the contents of the file <strong>app/views/layouts/application.html.erb</strong> with this:</p>
<pre>
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<title><%= content_for?(:title) ? yield(:title) : "Myapp" %></title>
<meta name="description" content="">
<meta name="author" content="">
<%= stylesheet_link_tag "application", :media => "all" %>
<%= javascript_include_tag "application" %>
<%= csrf_meta_tags %>
<%= yield(:head) %>
</head>
<body>
<header class="navbar navbar-fixed-top">
<nav class="navbar-inner">
<div class="container">
<%= render 'layouts/navigation' %>
</div>
</nav>
</header>
<div id="main" role="main">
<div class="container">
<div class="content">
<div class="row">
<div class="span12">
<%= render 'layouts/messages' %>
<%= yield %>
</div>
</div>
<footer>
</footer>
</div>
</div> <!--! end of .container -->
</div> <!--! end of #main -->
</body>
</html>
</pre>
<h3>Default Application Layout with Twitter Bootstrap (Haml)</h3>
<p>If you are using Haml, remove <strong>app/views/layouts/application.html.erb</strong> and replace it with <strong>app/views/layouts/application.html.haml</strong> with the following content:</p>
<pre>
!!!
%html
%head
%meta{:charset => "utf-8"}
%meta{"http-equiv" => "X-UA-Compatible", :content => "IE=edge,chrome=1"}
%meta{:name => "viewport", :content => "width=device-width, initial-scale=1, maximum-scale=1"}
%title= content_for?(:title) ? yield(:title) : "Myapp"
%meta{:content => "", :name => "description"}
%meta{:content => "", :name => "author"}
= stylesheet_link_tag "application", :media => "all"
= javascript_include_tag "application"
= csrf_meta_tags
= yield(:head)
%body
%header.navbar.navbar-fixed-top
%nav.navbar-inner
.container
= render 'layouts/navigation'
#main{:role => "main"}
.container
.content
.row
.span12
= render 'layouts/messages'
= yield
%footer
</pre>
<h2>Navigation Links</h2>
<p>You’ll likely need navigation links on every page of your web application. You’ll want a link for Home. If you’ve implemented authentication using <a href="http://github.com/plataformatec/devise">Devise</a> you’ll want links for Login, Logout, and Sign Up. If you’re using <a href="https://github.com/intridea/omniauth">OmniAuth</a> for authentication, you’ll want links for Login and Logout. If you’ve got pages for an administrator, you may want a link for Admin.</p>
<p>You can add navigation links directly to your application layout file but many developers prefer to create a <a href="http://guides.rubyonrails.org/layouts_and_rendering.html#using-partials">partial template</a> – a “partial” – to better organize the default application layout.</p>
<h3>Example Navigation Links for Devise (<span class="caps">ERB</span>)</h3>
<p>Create the file <strong>app/views/layouts/_navigation.html.erb</strong> for the navigation links.</p>
<p>If you’re using Devise, use these navigation links:</p>
<pre>
<%= link_to "Home", root_path, :class => 'brand' %>
<ul class="nav">
<% if user_signed_in? %>
<li>
<%= link_to('Logout', destroy_user_session_path, :method=>'delete') %>
</li>
<% else %>
<li>
<%= link_to('Login', new_user_session_path) %>
</li>
<% end %>
<% if user_signed_in? %>
<li>
<%= link_to('Edit account', edit_user_registration_path) %>
</li>
<% else %>
<li>
<%= link_to('Sign up', new_user_registration_path) %>
</li>
<% end %>
</ul>
</pre>
<h3>Example Navigation Links for Devise (Haml)</h3>
<p>For Haml with Devise, create the file <strong>app/views/layouts/_navigation.html.haml</strong>:</p>
<pre>
= link_to "Home", root_path, :class => 'brand'
%ul.nav
- if user_signed_in?
%li
= link_to('Logout', destroy_user_session_path, :method=>'delete')
- else
%li
= link_to('Login', new_user_session_path)
- if user_signed_in?
%li
= link_to('Edit account', edit_user_registration_path)
- else
%li
= link_to('Sign up', new_user_registration_path)
</pre>
<h2>Flash Messages with Twitter Bootstrap</h2>
<p>Rails provides a standard convention to display alerts (including error messages) and other notices, called Rails “flash messages” (as in “flash memory”, not to be confused with the “Adobe Flash” proprietary web development platform).</p>
<p>You can include code to display flash messages directly in your application layout file or you can create a partial.</p>
<p>Rails uses <code>:notice</code> and <code>:alert</code> as flash message keys. Twitter Bootstrap provides a base class <code>.alert</code> with additional classes <code>.alert-success</code> and <code>.alert-error</code> (see the <a href="http://twitter.github.com/bootstrap/components.html#alerts">Bootstrap documentation on alerts</a>). A bit of parsing is required to get a Rails “notice” message to be styled with the Twitter Bootstrap “alert-success” style. Any other message, including a Rails “alert” message, will be styled with the Twitter Bootstrap “alert-error” style.</p>
<p>Twitter Bootstrap provides a jQuery plugin named bootstrap-alert that makes it easy to dismiss flash messages with a click. The data-dismiss property displays an “x” that enables the close functionality. Note that Twitter Bootstrap uses the <span class="caps">HTML</span> entity “&#215;” instead of the keyboard letter “x”.</p>
<p>By default, Twitter Bootstrap applies a green background to <code>.alert-success</code> and a red background to <code>.alert-error</code>. Twitter Bootstrap provides a third class <code>.alert-info</code> with a blue background. With a little hacking, it’s possible to create a Rails flash message with a custom name, such as <code>:info</code>, that will display with the Bootstrap <code>.alert-info</code> class. However, it’s wise to stick with the Rails convention of using only “alert” and “notice.”</p>
<h3>Flash Messages with Twitter Bootstrap (<span class="caps">ERB</span>)</h3>
<p>For <span class="caps">CSS</span> styling with Twitter Bootstrap, create a partial for flash messages in <strong>app/views/layouts/_messages.html.erb</strong> like this:</p>
<pre>
<% flash.each do |name, msg| %>
<div class="alert alert-<%= name == :notice ? "success" : "error" %>">
<a class="close" data-dismiss="alert">×</a>
<%= content_tag :div, msg, :id => "flash_#{name}" if msg.is_a?(String) %>
</div>
<% end %>
</pre>
<h3>Flash Messages with Twitter Bootstrap (Haml)</h3>
<p>For <span class="caps">CSS</span> styling with Twitter Bootstrap using Haml, create a partial for flash messages in <strong>app/views/layouts/_messages.html.haml</strong> like this:</p>
<pre>
- flash.each do |name, msg|
%div{:class => "alert alert-#{name == :notice ? "success" : "error"}"}
%a.close{"data-dismiss" => "alert"} ×
= content_tag :div, msg, :id => "flash_#{name}" if msg.is_a?(String)
</pre>
<h2>Options and Improvements</h2>
<p>This introduction gives you the basics of Twitter Bootstrap with Rails, including messages for alerts and notices, and an application layout using Twitter Bootstrap.</p>
<p>There’s much more you can do with Twitter Bootstrap. For an advanced example, see the RailsApp <a href="https://github.com/RailsApps/rails-prelaunch-signup">rails-prelaunch-signup</a> example app. The <a href="http://railsapps.github.com/tutorial-rails-prelaunch-signup.html">rails-prelaunch-signup tutorial</a> shows how you can use Twitter Bootstrap to add a modal window and <span class="caps">AJAX</span> for a “sign up” form for a “Web 2.0” application. When the visitor submits the form, the modal window changes to display a “thank you” message (or an error message) without a page refresh.</p>
<p>Suggestions? Improvements? Please leave a comment.</p>
</div><!-- class="content" -->
<div class="comments">
<div class="content wikistyle gollum">
<h2>Comments</h2>
</div>
<p>Is this helpful? Please "like" below. Question or suggestion? Please add a comment below. Got a correction or addition? You can edit this page <a href="https://github.com/RailsApps/railsapps.github.com/wiki/_pages">on the wiki</a> or create a <a href="https://github.com/RailsApps/railsapps.github.com/issues">GitHub issue</a> to alert me.</p>
<div id="disqus_thread"></div>
<script type="text/javascript">
/* * * CONFIGURATION VARIABLES: EDIT BEFORE PASTING INTO YOUR WEBPAGE * * */
var disqus_shortname = 'railsapps'; // required: replace example with your forum shortname
/* * * DON'T EDIT BELOW THIS LINE * * */
(function() {
var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
dsq.src = 'http://' + disqus_shortname + '.disqus.com/embed.js';
(document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
})();
</script>
<noscript>Please enable JavaScript to view the <a href="http://disqus.com/?ref_noscript">comments powered by Disqus.</a></noscript>
<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>
</div><!-- class="comments" -->
<div class="footer row">
<div class="span4">
<h3>Credits</h3>
<p><a href="http://danielkehoe.com/">Daniel Kehoe</a> initiated the <a href="http://railsapps.github.com/">RailsApps Project</a>. Thanks to <a href="http://tigrish.com/">Christopher Dell</a> for design contributions.</p>
</div>
<div class="span4">
<h3>Contributions</h3>
<p>Corrections? Additions? You can edit this page <a href="https://github.com/RailsApps/railsapps.github.com/wiki/_pages">on the wiki</a>.</p>
</div>
<div class="span4">
<h3>Last edit</h3>
<p>by <b>Daniel Kehoe</b>, 2012-05-19 20:21:06</p>
</div>
</div>
</div>
</body>
</html>