Foundation Markup

As a Rails Front End Engineer I look at layout as the Rails templating system where all of my front end code lives and interacts – via Rails – with the outside world. In this chapter of The Front End Manifesto we will focus on:

Setting up a basic HTML foundation for an application
Getting it right per our manifesto

NOTE: Chapter 1 of the sequel to this book, Coding Design, provides a great introduction to information architecting in case you're interested.

Views

The templating system and associated files and folders used in Rails are known as Views, the V in MVC. View code is primarily found in two high-level folders within a Rails 3.0 or greater application: the helpers and the views folders...

app
├─ assets
├─ controllers
├─ helpers
├─ mailers
├─ models
└─ views
      ├─ layout
       |    └─ application.html.haml
      └─ shared

Most of the action takes place in the views folder which can be further subdivided into of the layout and shared folders – home to the majority of your foundation front end code.

The heart of the Rails templating system by default is application.html.haml. View code from other parts of an application pass through and become framed by application.html.haml before being served to browsers.

The Code

To help you build your own foundation markup I will provide links to generic starter code. I will reference this code throughout this book, and feel free to use this code for your own projects.

Structurally our starter code files and folders fall into place as follows:

The default Rails file structure and starter code file structure are pretty much identical by design; so that you can cut and paste it into your project in one action. In the next section we will start our own implementation of a rails front-end by creating a new Rails application and replacing out-of-the-box Rails files with our starter code. Folders we add are depicted above in bold. New or replacement files include links to their respective github source for your inspection.

NOTE: Our starter code is predominantly an implementation of HTML5 Boilerplate (v 4.3.0) in haml arranged for a Rails project. In my experience the best place to reference when building front-end view templates is HTML5 Boilerplate. This resource is an ongoing collaboration between expert front-end developers and the community. Although slightly dated, the following article provides a decent overview of HTML5 Boilerplate as it applies to Rails:

Guide to HTML5 Boilerplate for Rails Developers

Foundation Set Up

Setting up the foundation markup of a Rails application is super straightforward. In fact if I were you I would just bookmark this page and every time you build a new application follow the Groundwork Tasks and Prep and Launch steps below.

NOTE: The secret sauce comes from the starter code, everything else will be pretty routine from application to application.

Groundwork Tasks

Task 1: Clone Starter Code

Clone this books starter code:

git clone git@github.com:maxxiimo/base-haml.git

Task 2: Create a Rails Application

Create a brand-new Rails application:

$ rails new <name> --skip-test-unit

NOTE: A great reference for doing this correctly is Chapter 1 and 3 of Michael Hartl's "Ruby on Rails Tutorial". In Chapter 3 Listing 3.2 Michael discusses dynamically generating a secret token. If you're considering implementing this solution also take a look at:

Better Secret_Token Management for Rails

Task 2: Version Control

In the Rails world Git is the versioning sytem of choice. Here are the steps to follow when creating a new Rails application:

$ cd /path/to/my/repo
$ git init
$ git add .
$ git commit -am "Initial commit."

Github is a popular code collaboration, management and repository service I recommend you open an account on if you haven't done so already. To push your new application to github follow these steps:

Create a new repo at Github.
$ git remote add origin git@github.com:<Github username>/<application name>.git
$ git push -u origin master

Bitbucket is an alternative service you can use:

$ git remote add origin ssh://git@bitbucket.org/maxxiimo/<repository>.git
$ git push -u origin --all   # pushes up the repo and its refs for the first time
$ git push -u origin --tags  # pushes up any tags

Task 3: Remove Unnecessary Files

Out-of-the-box Rails 3.x comes with a few files that should be deleted. After testing that your application works, delete:

public/index.html
assets/images/rails.png

In Rails 3.x and greater the following two files can be deleted:

app/views/layouts/application.html.erb
README.rdoc

These files will be replaced in the next task with files from our starter code: application.html.haml and README.md.

Commit your changes.

Task 4: Add Starter Code

Go ahead and copy all the files and folders from your cloned starter code repository into your existing application structure.

NOTE: You should be able to copy/merge the files into your application in one action; they will fall into place or replace existing files correctly. If you are using Rails 4.0.0 delete the file Gemfile [Rails 3.2.13]. If you are using Rails 3.2 .13, delete the existing Gemfile and rename Gemfile [Rails 3.2.13] to Gemfile.

The following files will be modified or added to your repository:

Commit your changes.

Task 5: Bundle Install

Install your new gems:

$ bundle install --without production

IMPORTANT: Michael Hartl recommends using the '--without production' flag on your first bundle. Doing so installs your Gemfile gems, but prevents the installation of production gems. You only have to do this once.

NOTE: Our starter code Gemfile includes better error testing gems, which you may uncomment if you plan to use them:

  # http://railscasts.com/episodes/402-better-errors-railspanel
  # gem 'better_errors'
  # gem 'binding_of_caller'
  # gem 'meta_request'

Commit your changes.

Task 6: RSpec

To set up rspec run the following:

$ rails generate rspec:install

Commit your changes.

For faster asset precompiles check out:

Turbo Sprockets for Rails 3.2.x

Task 7: Deployment

Heroku is a cloud application platform used by many members of the Rails community. If you do not already have a Heroku account you will need to open one and set up your computer with that account. Deploy to Heroku by running the following commands:

$ heroku create --stack cedar
$ git push heroku master
$ heroku rename <new name>

IMPORTANT: You will have problems precompiling modernizr-2.8.3.min.js. It's not part of your manifest, therefore you will need to tell Heroku to precompile this file:

Add the following to production.rb:

config.assets.precompile += %w( modernizr-2.8.3.min.js )

And that's it! Now it's time to Prep and Launch your application.

Prep and Launch

Step 1: If you do not have a page for your routes to go to, which I'm assuming you don't if this is a brand-new application, create one now. Generate a pages controller with some very basic static pages:

$ rails generate controller Pages home about terms privacy contact

Make sure to delete the assets/stylesheets/pages.css.scss file generated by Rails, we won't be using it. You can also delete assets/javascripts/pages.js.coffee if you do not plan to use it.

Commit your changes.

Step 2: Change your default route to whatever you want your application to default to:

root :to => 'pages#home'

In Rails 3.2 swap out your get routes with match routes:

match 'home'     => 'pages#home'
match 'about'    => 'pages#about'
match 'terms'    => 'pages#terms'
match 'privacy'  => 'pages#privacy'
match 'contact'  => 'pages#contact'

Commit your changes.

Step 3: Finally, we'll need to do a little housekeeping. If you open views/layouts/_head.html.haml you'll notice quite a lot of commented out code. You can safely delete all of this. It's there to give you options, things you could use but are not entirely necessary.

Also, replace the "XXX" with whatever title and description you would like to use.

%title= content_for?(:title) ? yield(:title) : "XXX"
-# alternative title format.
-# %title= content_for?(:title) ? ("XXX - " + yield(:title)) : "XXX"

%meta{:name => "description", :content => "XXX"}

NOTE: For title formats you have two choices. Choose one and delete the other. To yield a title from a page add the following code to the top of your views:

- content_for :title do
  Some Title Here

For example, at the top of views/pages/home.html.haml:

- content_for :title do
  Home

Commit your changes.

Step 4: It's time to launch! If you run WEBrick, your application should now just work with the following command:

$ rails server

...and in your browser location box type:

localhost:3000