RailsLayout Gem
Use this gem to set up layout files for your choice of front-end framework:
- Zurb Foundation 5.0
- Zurb Foundation 4.0
- Bootstrap 3.0
- Bootstrap 2.3
Plus it will set up Devise views with styling for Bootstrap or Foundation.
RailsLayout is a utility gem to use during development.
Rails Composer
The RailsLayout gem is used by Rails Composer tool, an application template used to create starter applications. You can use Rails Composer to generate entire applications.
Support the RailsApps Project
If the RailsLayout gem is useful to you, please accept our invitation to join the RailsApps project. The RailsApps project provides example applications, tutorials, and starter tools, including the RailsLayout gem.
Command Summary
Generate Application Layout, Navigation, and Flash Message Files
$ rails generate layout:install foundation5
$ rails generate layout:install foundation4
$ rails generate layout:install bootstrap3
$ rails generate layout:install bootstrap2
$ rails generate layout:install simple
$ rails generate layout:install none
Add Links to the Navigation File
$ $ rails generate layout:navigation
Generate Devise Views
$ rails generate layout:devise foundation5
$ rails generate layout:devise bootstrap3
Installing a Front-End Framework
Refer to instructions for:
In summary, to install a front-end framework, add the gems you need. Then use the RailsLayout gem. It will set up your assets files.
Add the gems you need to your Rails application Gemfile:
Zurb Foundation 5.0
gem 'foundation-rails'
Note: Check the status of these issues before using Foundation 5.0:
- Foundation 5 requires JavaScript included in BODY not HEAD
- Foundation 5 topbar incompatible with Rails Turbolinks
Zurb Foundation 4.0
gem 'compass-rails'
gem 'zurb-foundation'
Bootstrap 3.0
gem 'bootstrap-sass'
Bootstrap 2.3
gem 'bootstrap-sass', '~> 2.3.2.2'
Use Bundler
Use Bundler to install the gem:
$ bundle install
Install the RailsLayout Gem
Add it to your Rails application Gemfile:
group :development do
gem 'rails_layout'
end
You don’t need the gem deployed to production, so put it in the development
group.
If you want to use a newer unreleased version from GitHub:
group :development do
gem 'rails_layout', github: 'RailsApps/rails_layout'
end
Use Bundler to install the gem:
$ bundle install
The “layout:install” Command
The command will rename application.css to application.css.scss.
It will add:
- framework_and_overrides.css.scss
And modify the JavaScript asset file:
- application.js
It will set up a default application layout.
It creates partials for:
- Rails flash messages
- navigation links
Supported Frameworks
You can generate layout files suitable for use with the following front-end frameworks:
foundation5
– Zurb Foundation 5.0foundation4
– Zurb Foundation 4.0bootstrap3
– Bootstrap 3.0bootstrap2
– Bootstrap 2.3simple
– simple layoutnone
– removes all changes
Generated Files
The RailsLayout gem generates application layout files:
- app/views/layouts/application.html.erb
- app/views/layouts/_messages.html.erb
- app/views/layouts/_navigation.html.erb
- app/views/layouts/_navigation_links.html.erb
Additionally, when the simple
option is selected:
- app/assets/stylesheets/simple.css
Note About the Navigation Partials
Two navigation partials are created:
- app/views/layouts/_navigation_links.html.erb
- app/views/layouts/_navigation.html.erb
The first file contains no framework-specific styling. It is only a list of links. You can add additional links to this file as needed.
The second file contains framework-specific styling.
Support for ERB, Haml, or Slim
If you are using ERB for Rails views, the RailsLayout gem will generate ERB files.
If you are using Haml or Slim, the RailsLayout gem will generate Haml or Slim files instead.
Additional Documentation
See these articles for information about how to set up the application layout:
Look at the Learn Rails example application to see how the generated files from the RailsLayout gem are used. You’ll find details about the example application in the book Learn Ruby on Rails.
Zurb Foundation 5.0 Layout
To create layout files for use with Zurb Foundation 5.0:
$ rails generate layout:install foundation5
Use --force
if you want to overwrite existing files:
$ rails generate layout:install foundation5 --force
See the files that are generated:
- app/views/layouts/application.html.erb
- app/views/layouts/_messages.html.erb
- app/views/layouts/_navigation.html.erb
The RailsLayout gem will create the file:
and modify the file:
Zurb Foundation 4.0 Layout
To create layout files for use with Zurb Foundation 4.0:
$ rails generate layout:install foundation4
Use --force
if you want to overwrite existing files:
$ rails generate layout:install foundation4 --force
See the files that are generated:
- app/views/layouts/application.html.erb
- app/views/layouts/_messages.html.erb
- app/views/layouts/_navigation.html.erb
The RailsLayout gem will create the file:
and modify the file:
Bootstrap 3.0 Layout
To create layout files for use with Bootstrap 3.0:
$ rails generate layout:install bootstrap3
Use --force
if you want to overwrite existing files:
$ rails generate layout:install bootstrap3 --force
See the files that are generated:
- app/views/layouts/application.html.erb
- app/views/layouts/_messages.html.erb
- app/views/layouts/_navigation.html.erb
The RailsLayout gem will create the file:
and modify the file:
Bootstrap 2.3 Layout
To create layout files for use with Bootstrap 2.3:
$ rails generate layout:install bootstrap2
Use --force
if you want to overwrite existing files:
$ rails generate layout:install bootstrap2 --force
See the files that are generated:
- app/views/layouts/application.html.erb
- app/views/layouts/_messages.html.erb
- app/views/layouts/_navigation.html.erb
The RailsLayout gem will create the file:
and modify the file:
Generate a Simple Layout
To create a set of simple layout files:
$ rails generate layout:install simple
Use --force
if you want to overwrite existing files:
$ rails generate layout:install simple --force
See the files that are generated:
- app/views/layouts/application.html.erb
- app/views/layouts/_messages.html.erb
- app/views/layouts/_navigation.html.erb
- app/assets/stylesheets/simple.css
The RailsLayout gem will create the file:
Reverting to None
To revert your application to a default application layout:
$ rails generate layout:install none
The RailsLayout gem will remove any files it may have added:
- app/views/layouts/_messages.html.erb
- app/views/layouts/_navigation.html.erb
- app/assets/stylesheets/simple.css
- app/assets/stylesheets/bootstrap_and_overrides.css.scss
- app/assets/stylesheets/foundation_and_overrides.css.scss
- app/assets/stylesheets/framework_and_overrides.css.scss
Additionally, it will restore these files to the default versions:
- app/views/layouts/application.html.erb
- app/assets/javascripts/application.js
The file app/assets/stylesheets/application.css.scss will contain a CSS rule but you can ignore it or remove it.
The “layout:navigation” Command
If you are using Devise for authentication, you can generate a navigation links partial containing links for Devise.
This command is used to populate the navigation bar in starter applications created by the Rails Composer tool.
$ rails generate layout:navigation --force
This creates a file app/views/layouts/_navigation_links.html.erb:
<%# add navigation links to this file %>
<li><%= link_to 'Home', root_path %></li>
<li><%= link_to 'About', page_path('about') %></li>
<li><%= link_to 'Contact', new_contact_path %></li>
<% 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 %>
<% if user_signed_in? %>
<% if current_user.has_role? :admin %>
<li><%= link_to 'Admin', users_path %></li>
<% end %>
<% end %>
The full set of links will be created if the following files are found in your application:
- app/views/devise/sessions/new.html.erb
- app/views/devise/registrations/new.html.erb
- app/views/users/index.html.erb
The “layout:devise” Command
Devise is a gem for authentication and user management (signup, login, and related features). Devise provides a utility command rails generate devise:views
. The Devise command creates view files for signup, login, and related features. However, the views generated by Devise lack CSS styling.
Use the RailsLayout gem to generate Devise views with styling for Bootstrap or Foundation.
$ rails generate layout:devise foundation5
$ rails generate layout:devise bootstrap3
The command will create (or replace) these files:
- app/views/devise/sessions/new.html.erb
- app/views/devise/passwords/new.html.erb
- app/views/devise/registrations/edit.html.erb
- app/views/devise/registrations/new.html.erb
Additionally, the command will update a file to append Sass mixins to accommodate Bootstrap or Foundation:
- app/assets/stylesheets/framework_and_overrides.css.scss
The Sass mixins allow any view to be used with either Bootstrap or Foundation (so we don’t have to maintain separate views for each front-end framework).
Limitations
At this time, with the “layout:devise” command, only Foundation 5 or Bootstrap 3 are supported. Files are not generated for Haml or Slim.
Issues
Any issues? Please create an issue on GitHub. Reporting issues (and patching!) helps everyone.
Credits
Daniel Kehoe maintains this gem as part of the RailsApps project.
Please see the CHANGELOG for a list of contributors.
Is the gem useful to you? Follow the project on Twitter: @rails_apps. I’d love to know you were helped out by the gem.
MIT License
Copyright © 2013-2014 Daniel Kehoe