h1. !http://railsapps.github.io/images/rails-36x36.jpg(RailsLayout Gem)! RailsLayout Gem

RailsLayout is a utility gem to use during development.

Use it to set up your choice of front-end framework:

* Bootstrap 2.3
* Bootstrap 3.0
* Zurb Foundation 4.0
* Zurb Foundation 5.0

Add it to your Rails application Gemfile, then use the generator.

It 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

You can also generate a navigation links file suitable for use with Devise (the authentication gem).

h4. Supported Frameworks

You can generate layout files suitable for use with the following front-end frameworks:

* @simple@ - simple layout
* @bootstrap2@ - Bootstrap 2.3
* @bootstrap3@ - Bootstrap 3.0
* @foundation4@ - Zurb Foundation 4.0
* @foundation5@ - Zurb Foundation 5.0
* @none@ - removes all changes

h4. 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

h4. 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.

h4. 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.

h4. Rails Composer

The "Rails Composer":http://railsapps.github.io/rails-composer/ tool, an application template used to create starter applications, uses the RailsLayout gem to generate the layout files used in various starter applications. You can use Rails Composer to generate entire applications.

h4. Usage Example

Look at the "Learn Rails":https://github.com/RailsApps/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":http://learn-rails.com/learn-ruby-on-rails.html.

!http://railsapps.github.io/images/learn-rails-cover-130x161.jpg(Learn Ruby on Rails)!:http://learn-rails.com/learn-ruby-on-rails.html

h4. Documentation

See these articles for information about how to set up the application layout:

* "*Rails Application Layout*":http://railsapps.github.io/rails-default-application-layout.html
* "*Rails and Bootstrap*":http://railsapps.github.io/twitter-bootstrap-rails.html
* "*Rails and Foundation*":http://railsapps.github.io/rails-foundation.html

h2. Installing a Front-End Framework

Instead of following the "instructions for Bootstrap":http://railsapps.github.io/twitter-bootstrap-rails.html or "Zurb Foundation":http://foundation.zurb.com/docs/rails.html 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:

h4. Bootstrap 2.3

<pre>
gem 'bootstrap-sass', '~> 2.3.2.2'
</pre>

h4. Bootstrap 3.0

<pre>
gem 'bootstrap-sass'
</pre>

h4. Zurb Foundation 4.0

<pre>
gem 'compass-rails'
gem 'zurb-foundation'
</pre>

h4. Zurb Foundation 5.0

<pre>
gem 'foundation-rails'
</pre>

Note: Check the status of these issues before using Foundation 5.0:

* "Foundation 5 requires JavaScript included in BODY not HEAD":https://github.com/zurb/foundation/issues/3643
* "Foundation 5 topbar incompatible with Rails Turbolinks":https://github.com/zurb/foundation/issues/3642

h4. Use Bundler

Use Bundler to install the gem:

<pre>
$ bundle install
</pre>

h2. Install the RailsLayout Gem

Add it to your Rails application Gemfile:

<pre>
group :development do
  gem 'rails_layout'
end
</pre>

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:

<pre>
group :development do
  gem 'rails_layout', github: 'RailsApps/rails_layout'
end
</pre>

Use Bundler to install the gem:

<pre>
$ bundle install
</pre>

h2. Generate an Application Layout

Generate application layout files for the framework you will use.

h3. Generate a Simple Layout

To create a set of simple layout files:

<pre>
$ rails generate layout simple
</pre>

Use @--force@ if you want to overwrite existing files:

<pre>
$ rails generate layout simple --force
</pre>

See the files that are generated:

* "app/views/layouts/application.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/simple-application.html.erb
* "app/views/layouts/_messages.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/simple-messages.html.erb
* "app/views/layouts/_navigation.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/simple-navigation.html.erb
* "app/assets/stylesheets/simple.css":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/simple.css

The RailsLayout gem will create the file:

* "app/assets/stylesheets/application.css.scss":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/application.css.scss

h3. Bootstrap 2.3 Layout

To create layout files for use with Bootstrap 2.3:

<pre>
$ rails generate layout bootstrap2
</pre>

Use @--force@ if you want to overwrite existing files:

<pre>
$ rails generate layout bootstrap2 --force
</pre>

See the files that are generated:

* "app/views/layouts/application.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap2-application.html.erb
* "app/views/layouts/_messages.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap2-messages.html.erb
* "app/views/layouts/_navigation.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap2-navigation.html.erb

The RailsLayout gem will create the file:

* "app/assets/stylesheets/framework_and_overrides.css.scss":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap2_and_overrides.css.scss

and modify the file:

* "app/assets/javascripts/application.js":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap-application.js

h3. Bootstrap 3.0 Layout

To create layout files for use with Bootstrap 3.0:

<pre>
$ rails generate layout bootstrap3
</pre>

Use @--force@ if you want to overwrite existing files:

<pre>
$ rails generate layout bootstrap3 --force
</pre>

See the files that are generated:

* "app/views/layouts/application.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap3-application.html.erb
* "app/views/layouts/_messages.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap3-messages.html.erb
* "app/views/layouts/_navigation.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap3-navigation.html.erb

The RailsLayout gem will create the file:

* "app/assets/stylesheets/framework_and_overrides.css.scss":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap3_and_overrides.css.scss

and modify the file:

* "app/assets/javascripts/application.js":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/bootstrap-application.js

h3. Zurb Foundation 4.0 Layout

To create layout files for use with Zurb Foundation 4.0:

<pre>
$ rails generate layout foundation4
</pre>

Use @--force@ if you want to overwrite existing files:

<pre>
$ rails generate layout foundation4 --force
</pre>

See the files that are generated:

* "app/views/layouts/application.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation4-application.html.erb
* "app/views/layouts/_messages.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation4-messages.html.erb
* "app/views/layouts/_navigation.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation4-navigation.html.erb

The RailsLayout gem will create the file:

* "app/assets/stylesheets/framework_and_overrides.css.scss":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation4_and_overrides.css.scss

and modify the file:

* "app/assets/javascripts/application.js":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation4-application.js

h3. Zurb Foundation 5.0 Layout

To create layout files for use with Zurb Foundation 5.0:

<pre>
$ rails generate layout foundation5
</pre>

Use @--force@ if you want to overwrite existing files:

<pre>
$ rails generate layout foundation5 --force
</pre>

See the files that are generated:

* "app/views/layouts/application.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation5-application.html.erb
* "app/views/layouts/_messages.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation4-messages.html.erb
* "app/views/layouts/_navigation.html.erb":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation5-navigation.html.erb

The RailsLayout gem will create the file:

* "app/assets/stylesheets/framework_and_overrides.css.scss":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation5_and_overrides.css.scss

and modify the file:

* "app/assets/javascripts/application.js":https://github.com/RailsApps/rails_layout/blob/master/lib/generators/layout/templates/foundation5-application.js

h3. Reverting to None

To revert your application to a default application layout:

<pre>
$ rails generate layout none
</pre>

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.

h2. Navigation Links for Devise

If you are using Devise for authentication, you can generate a navigation links partial containing links for Devise.

<pre>
$ rails generate navigation --force
</pre>

This creates a file *app/views/layouts/_navigation_links.html.erb*:

<pre>
<%# 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 %>
</pre>

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

These files will be present in your application if you have created custom views for Devise.

The @rails generate navigation@ command is used to populate the navigation bar in starter applications created by the "Rails Composer":http://railsapps.github.io/rails-composer/ tool.

h2. Help

To see help messages:

<pre>
$ rails generate layout --help
</pre>

h2. Issues

Any issues? Please create an "issue":http://github.com/RailsApps/rails_layout/issues on GitHub. Reporting issues (and patching!) helps everyone.

h2. Credits

Daniel Kehoe maintains this gem as part of the "RailsApps project":http://railsapps.github.io/.

Please see the "CHANGELOG":https://github.com/RailsApps/rails_layout/blob/master/CHANGELOG.textile for a list of contributors.

Is the gem useful to you? Follow the project on Twitter: "@rails_apps":http://twitter.com/rails_apps. I'd love to know you were helped out by the gem.

h2. MIT License

"MIT License":http://www.opensource.org/licenses/mit-license

Copyright © 2013 Daniel Kehoe

!https://cruel-carlota.pagodabox.com/b096716fb733287d5c3d5eec65aaa26b(githalytics.com alpha)!