Guide to HTML5 Boilerplate for Rails Developers

by Daniel Kehoe

Last updated 20 November 2011

This is a guide to HTML5 Boilerplate for Rails developers. Like Rails on the server side or “backend”, HTML5 Boilerplate provides structure and conventions for setting up HTML5, CSS3 styles, and Javascript for front-end development. It is a popular starting point for many front-end developers. However, some aspects of HTML5 Boilerplate are not useful for Rails projects. Sorting through the HTML5 Boilerplate documentation to find what’s useful for Rails can be confusing. This article lists each component of HTML5 Boilerplate and identifies its usefulness for Rails applications.

If You Are New to Rails

If you’re new to Rails, see What is Ruby on Rails?, the book Learn Ruby on Rails, and recommendations for a Rails tutorial.

Join RailsApps

What is the RailsApps Project?

This is an article from the RailsApps project. The RailsApps project provides example applications that developers use as starter apps. Hundreds of developers use the apps, report problems as they arise, and propose solutions. Rails changes frequently; each application is known to work and serves as your personal “reference implementation.” Each application is accompanied by a tutorial so there is no mystery code. Support for the project comes from subscribers. Please accept our invitation to join the RailsApps project.

About HTML5 Boilerplate

HTML5 Boilerplate has been available since August 10th, 2010. Paul Irish and Divya Manian launched HTML5 Boilerplate as a set of templates “collecting best practices and making an ideal project starting point.”

On a first encounter, it seems HTML5 Boilerplate includes “everything but the kitchen sink.” Even finding a succinct list of components can be overwhelming. There’s an excellent list of the HTML5 Boilerplate components in Jonathan Verrecchia’s Initializr Advanced Customization.

This article provides commentary plus links to the relevant HTML5 Boilerplate documentation for each component. Descriptions are available in several places on the HTML5 Boilerplate website:

Installing HTML5 Boilerplate in a Rails Application

Many developers use the RailsApps example apps or the Rails Composer tool (“like the ‘rails new’ command on steroids”) to create a starter app. You’ll get the useful features of HTML5 Boilerplate (as described here) when you start with a RailsApps application.

There are other popular Rails 3 application templates that include HTML5 Boilerplate:

(Are there others? Please suggest with a comment below.)

Or use a Ruby gem to add HTML5 Boilerplate to your application:

Useful for Rails Projects

Consider adding the following components to your Rails application.

Default Application Layout

The HTML5 Boilerplate index.html file shows how to structure a simple web page using HTML5 markup. Initializr provides a more complex index.html file that shows how to use the HTML5 <nav>, <article>, and <aside> tags. It is helpful to refer to these index.html examples when you create an application layout file.

If you are using HAML, you can convert the HTML to HAML markup using the Html2Haml website.

Viewport Metatag

Apple introduced the viewport metatag to help web developers improve the presentation of web pages on mobile devices. Setting a viewport tells the browser how content should fit on the device’s screen. Typically, you use the viewport meta tag to set the width and initial scale of the viewport. The HTML5 Boilerplate index.html page provides an example that sets the viewport to the width of the device with an initial scale of 1. You can add this to your Rails application layout.

<meta name="viewport" content="width=device-width,initial-scale=1">

The above example allows zooming, something that may be desirable for a web site but not a web app. We could prevent zooming with the following values:

<meta name="viewport" content="width=device-width,initial-scale=1,user-scalable=no">

Apple’s developer documentation on Configuring the Viewport offers all the details.

Google Analytics Snippet

Most developers want to use Google Analytics tracking for their web apps. The HTML5 Boilerplate index.html page includes the Google Analytics tracking code. As a Rails developer, you’ll likely add the code to your application layout. Alternatively you can use one of several Ruby gems that automatically insert Google Analytics code into your pages with a helper or Rack middleware. You don’t need to copy what’s provided in HTML5 Boilerplate but it offers a good reminder to add Google Analytics tracking.

Sample humans.txt File

HTML5 Boilerplate provides a sample humans.txt file. By convention, a humans.txt file lists the people who contributed to building the website. It also can include a colophon (notes about tools or software used to create the website). If you have a desire to be recognized or want to satisfy the curiosity of humans (those who know to look for the file), you can consider adding a humans.txt file.

Possibly Useful for Rails Projects

Depending on your requirements, the following components might be useful in your Rails application.

Chrome Frame

The HTML5 Boilerplate index.html page includes Javascript that prompts users of Internet Explorer 6 (IE6) to install the Google Chrome Frame browser plug-in. The X-UA-Compatible metatag is required to force the IE rendering engine to use Chrome Frame’s rendering engine. If your website uses HTML5 features and you wish to support users of Internet Explorer 6, you can add the Javascript to your application layout files. Web browser market share for Internet Explorer 6 is rapidly decreasing so you may not wish to support IE6.

Apple Touch Icons

HTML5 Boilerplate provides five icons that serve as favicons for Apple and Android mobile devices and tablets. The icons are versions of the orange stars used on the HTML5 Boilerplate website. For IOS devices such as the iPad or iPhone, these icons are used when a web page is added to the device’s home screen. For web pages that don’t specify a custom touch icon, a thumbnail screenshot of the page is used instead. Android has a default icon, and some systems fall back to the favicon if it is available. As a Rails developer, you probably won’t want the orange stars from HTML5 Boilerplate. Instead you might have a designer create a set of custom touch icons for your project or you may use one of several favicon generators to create your own icons. You may want to read Mathias Bynens’s Everything You Always Wanted to Know About Touch Icons to learn more.

Crossdomain.xml File

You don’t need this in your Rails app unless your app is used as a backend by a web client such as Flash or Silverlight. What’s Crossdomain.xml For? explains that “a cross-domain policy file is an XML document that grants a web client—such as Adobe Flash Player, Adobe Reader, etc.—permission to handle data across multiple domains.” Most developers will not need it.

Already Included in Rails Projects

There’s no need to add the following components to your Rails application.

404: Not Found Page

You won’t need to use HTML5 Boilerplate to add this. A “404: Not Found” page is provided by Rails when you generate a new Rails application.

Favicon

HTML5 Boilerplate provides a favicon. A zero byte favicon.ico file is provided by Rails when you generate a new Rails application so you don’t need to use HTML5 Boilerplate to add it. As a Rails developer, you might have a designer create a custom favicon for your project or you may use one of several favicon generators to create your own favicon. Browsers always request the favicon.ico file so a zero byte file named favicon.ico will eliminate 404 errors in your logfile.

Sample robots.txt File

A robots.txt file is provided by Rails when you generate a new Rails application so you don’t need to use HTML5 Boilerplate to add it. If you are deploying a site that is under development, you may want to modify robots.txt to block potential spidering while the site is unfinished.

Placeholder Javascript Files

HTML5 Boilerplate provides placeholder script.js and plugins.js files as a suggested location for site-specific Javascript. When you build a new Rails app, you’ll have a placeholder app/assets/javascripts/application.js file that works with the Rails asset pipeline. Don’t use the placeholder script.js and plugins.js files offered by HTML5 Boilerplate.

jQuery

The HTML5 Boilerplate index.html file shows how to add jQuery to a non-Rails web page. For a Rails app, don’t modify your application layout to match the HTML5 Boilerplate example. In Rails jQuery is the default JavaScript library. The default jquery-rails gem provides jquery.js and jquery_ujs.js files. You won’t need to include these files using <script> tags because they are automatically included via the Rails asset pipeline.

HTML5 Boilerplate recommends loading jQuery from Google’s CDN (content delivery network). You can write code that checks if a connection to the CDN is available, then checks if the version in the CDN matches the version in the jquery-rails gem, and falls back to the version in the Rails asset pipeline if the CDN is not available. If you do so, you’ll only save a single HTTP request (the first time a user visits the app). The assets pipeline produces a cached minified Javascript file which is used for all subsequent requests. For ultimate performance, you can consider using the CDN; for most projects, it’s probably not worth the extra code.

  • HTML5 Boilerplate’s jQuery
  • HTML5 Boilerplate’s description of jQuery

X-UA-Compatible Metatag

The HTML5 Boilerplate index.html page includes the X-UA-Compatible metatag. Versions 8 and 9 of Internet Explorer contain multiple rendering engines and the X-UA-Compatible metatag will force IE 8 or 9 to use the newest version of the IE rendering environment. Secondly, if Chrome Frame is installed, the X-UA-Compatible metatag will force IE 8 or 9 to use Chrome Frame’s rendering engine. As a Rails developer, you don’t have to add the X-UA-Compatible metatag to your application layout files or set an HTTP header in your ApplicationController. In production mode, the Rails ActionDispatch class automatically sends an HTTP header that sets the X-UA-Compatible header to IE=Edge,chrome=1. In development mode, the X-UA-Compatible header is set to IE=Edge. For a Rails app, there’s no need to use the X-UA-Compatible metatag snippet from HTML5 Boilerplate.

Not Useful for Rails Projects

You won’t need these components.

Web Server Configuration Files

These files will only be useful if you are a system admininstrator. If you are the system admininstrator for a web server, see Paul Irish’s best-practice server configurations for Apache, IIS, nginx, lighttpd, Google AppEngine, and NodeJS.

HTML and Javascript Support for CSS

You can use these components if you are implementing CSS styles for your application and need to support Internet Explorer versions 6, 7, or 8 or features that are missing from certain web browsers. If you are using a CSS toolkit such as Twitter Bootstrap or Zurb Foundation and intend to use only the provided (“pre-themed”) CSS styles, you can do without these components.

IE Conditional Comments (HTML Markup)

The HTML5 Boilerplate index.html page includes code that modifes the <html> tag to add CSS classes for older versions of Internet Explorer. This is HTML5 Boilerplate’s important contribution to cross-browser compatibility. For how it works, see Paul Irish’s Conditional stylesheets vs CSS hacks? Answer: Neither!. If you are designing with CSS and accommodating specific versions of Internet Explorer, you’ll find IE conditional comments are useful.

Modernizr (Javascript)

Modernizr is a Javascript library that detects browser features and installs shims, fallbacks, and polyfills to add HTML5 functionalities to browsers that don’t natively support them. It is useful as a foundation for building cross-browser-compatible HTML5 and CSS3 features. If you need to test whether a browser has CSS transitions and transforms (for example), you can use Modernizr. HTML5 Boilerplate’s CSS stylesheet does not depend on Modernizr. If you are relying solely on a CSS toolkit such as Twitter Bootstrap or Zurb Foundation, you won’t need Modernizr.

HTML5 Shiv (Javascript)

HTML5 Shiv is Javascript code that tricks older versions of Internet Explorer into applying CSS styling for HTML5 elements such as the <article> tag. Its use was first suggested in 2008 and it has been subsequently incorporated into Modernizr. You’ll only use it if you don’t need all the features of Modernizr but still need to style HTML5 elements in older versions of IE.

Respond (Javascript)

Scott Jehl’s Respond Javascript code enables min-width and max-width media queries in browsers (Internet Explorer 6, 7, and 8) that do not natively support CSS3 media queries. It makes it possible to do responsive web design in browsers that don’t support CSS3 media queries. Respond.js is offered as an option in the Modernizr download builder tool and HTML5 Boilerplate includes it as part of the default Modernizr Javascript file.

CSS Toolkit

You may need these components if you are implementing CSS styles for your application.

CSS Reset

As described by Eric Meyer, CSS Reset “smooths out many browser inconsistencies by explicitly assigning values to things like element margins and padding, forcing all elements to have the same font size, and so on. You can find resets in most CSS frameworks, and they’re a great starting point for creating your own ‘baseline’ styles.” HTML5 Boilerplate does not provide CSS rules for a complete CSS reset. Instead it offers CSS normalization.

CSS Normalization

CSS normalization provides a set of CSS rules that make HTML elements such as <h1> look the same across web browsers. For a sample, see a web page that uses normalized CSS from the normalize.css project by Nicolas Gallagher and Jonathan Neal. The HTML5 Boilerplate css.style file incorporates CSS normalization from the normalize.css project and adds a few rules of its own. If you use another CSS toolkit such as Twitter Bootstrap or Zurb Foundation, you won’t need the normalization from HTML5 Boilerplate.

CSS Print Styles

The HTML5 Boilerplate style.css file offers an example CSS media print style that is used when a web page is printed from a browser. It is a useful reference if you are writing your own CSS styles for printing.

CSS Media Queries for Responsive Design

You’ll want to design your Rails app to accommodate a variety of devices. The term responsive web design was coined by Ethan Marcotte and refers to using fluid grids, flexible images, and CSS3 media queries to modify a web page to accommodate devices with differing screen sizes and resolutions such as a smartphones, tablets, and desktop computers. A media query in a CSS stylesheet (such as media screen and (max-width:320px)) can detect the width of a smartphone’s screen and adjust CSS rules accordingly. HTML5 Boilerplate provides placeholders for media queries in its style.css file but does not provide CSS styles for different devices. You can use a CSS toolkit such as Skeleton or Zurb Foundation to design sites that adapt to different browser page sizes.

CSS Paged Media Styles

Paged media support means browsers will break content into pages to accommodate orphans/widows. The HTML5 Boilerplate style.css file includes CSS rules for paged media. Paged media is supported only in a few browsers. You probably don’t need this.

CSS Helper Classes

The HTML5 Boilerplate style.css file includes several CSS classes that are often needed by web designers. You’ll probably use some of these if you are not using another CSS toolkit.

CSS Grid

HTML5 Boilerplate does not provide a CSS grid system. You can add a CSS toolkit that provides a grid system.

Conclusion

The HTML5 Boilerplate project integrates the research and thought of a large community of front-end developers. In its downloadable form, HTML5 Boilerplate doesn’t fit easily into a typical Rails application. However, HTML5 Boilerplate serves as a useful reference for Rails developers who want to provide structure and convention for the HTML, CSS, and Javascript of an application’s front-end. Hopefully, with this guide, you can pick and choose the components that are useful for a Rails app. In the process, you’ll learn about current best practices for front-end development.

Did You Like the Article?

Was the article useful to you? Follow @rails_apps on Twitter and tweet some praise. I’d love to know you were helped out by the article.

You can also find me on Facebook or Google+.

Contributors

Thank you to Nicolas Gallagher and Peter Cooper for commenting on the first draft of this article.

Comments

Is this helpful? Your encouragement fuels the project. Please tweet or add a comment. Couldn't get something to work? For the example apps and tutorials, it's best to open an issue on GitHub so we can help you.

comments powered by Disqus