Using Haml with Rails 3

Show Notes

In this video tutorial we’ll cover how to use Haml in a new Rails project, how to integrate it into an existing project, and how to convert any pre-existing ERB templates into Haml.

If you’re new to Haml, we recommend you first watch our Introduction to Haml screencast.


What you'll learn

  • How to include haml and appropriate haml generators for Rails 3
  • How to recursively change all ERB files to Haml using a custom rake task

Using Haml with Rails 3

Welcome to the Using Haml with Rails 3 screencast. Today we’ll cover how to use Haml in a new Rails project, how to integrate it into an existing project, and how to convert any pre-existing ERB templates into Haml.

If you’re new to Haml, we recommend you first watch our Introduction to Haml screencast, available on

Haml in a new Rails 3 Project

Lets first create a new project. To do this, we simply type rails new store

Now let’s go into our Gemfile and add the line: gem "haml-rails"

When installed, this Gem includes Haml as a dependency along with a series of generators for scaffolding, mailers and controllers.

Next we run bundle install to install the gems in our Gemfile.

Then, we type: rails generate scaffold Product (the name of our Model) then name:string (our first attribute name which is a string, then) price:float (our other attributes which is a float).

Then we see that all of the expected views are being generated, but now they’re being created in Haml, as opposed to Erb.

Now the only thing left to do is convert our application.html.erb to Haml. You don’t have to do this, since haml and erb do play nicely with each other. However, if you want to go Haml all-the-way, you can convert this one of two ways:

To do it manually, remove all of the file’s HTML and Erb markup and replace it with Haml. Also be sure to rename the file extension from dot erb to dot haml.

The other way is to use a command line tool which takes us on to our next section, adding Haml to an Existing Project.

Haml in an Existing Rails 3 Project

Here we have another store application, but this time it was built with Erb.

Like before, we add the haml-rails gem to our Gemfile, and then we run bundle install. We should now have a command line tool called html2haml.

There are some dependencies we’ll have to install for html2haml to work properly, and you’ll see why shortly. These dependencies aren’t included automatically, since the standard conversion direction is Haml to HTML not vice versa. So we’ll add these dependencies.

The three dependencies are: Hpricot, for HTML parsing, Erubis, to Parse Erb, and ruby_parser, to parse ruby code.

So we’ll now add the following to our Gemfile in the development group. We don’t need to include Erubis here, since that’s already included as a dependency of ActionPack.

We run bundle install to install these gems...

… and now that they’re installed, we can do the conversion.

We change directory to app/views/layouts and type html2haml application.html.erb

As you can see from the console output, we’ve converted the application.html.erb file from HTML (and Erb) to Haml. Now we can output this into a file using redirection. If we use the greater than symbol after a command, we redirect the output into the file name given. So we now have a file called application.html.haml that contains the newly converted Haml from our original .erb file.

Now, of course this can be time consuming going into each directory to rewrite every page, so instead, let’s make something that will recursively look in our app/views folder and rewrite all of our Erb files as Haml.

There are bash scripts out there, but just copying and pasting one and hoping it works isn’t a practice we’d advocate. Also, since Ruby code is more familiar to us and more readable, let’s write a rake task to do it ourselves.

Under the Hood

The html2haml code uses the Haml::HTML class, and as you can see, it requires those 3 gems we mentioned earlier to function.

So in order to create Haml from HTML, we pass in a string of html as the first argument to the constructor, with the :erb value set to true. Then, we call render to obtain the Haml, which can then be saved to a file.

OK, so here we have a custom rake task already setup in lib/tasks called hamlify.rake.

Here is the code that we’ve already prepared.

First we need to require the haml/html class. Then we need to cycle through the erb files in the views folder.

We then create a haml_file_name variable to store the location of the new haml file. We check if it already exists, just in case someone else has already done this conversion. If it doesn’t already exist, we open the erb-file-to-convert, then pass its contents to the converter to obtain a string of Haml. Then, we write it out to the new Haml file location, and delete the old Erb file.

Before running this task, it’s important to note that we should always use a version control system, just in case things don’t go according to plan. In other words, when you’re potentially deleting all of your view files, it’s good to have a rollback strategy!

So let’s run this task by running rake hamlify:convert. And as you can see, it has Hamlified all of our views! And that’s it! So now you’re up-to-speed on incorporating Haml into new and existing Rails 3 projects.

Thanks for watching! Subscribe to our RSS feed, follow us on Twitter, and please leave any questions, comments or suggestions for new screencasts in the comments below. If you like our videos, and think your friends, followers or colleagues would benefit from seeing them, please feel free share via any of the links below the video. We really appreciate your support.

See you next time!