Haml and Rails
by Daniel Kehoe
Last updated 2 April 2013
Using Haml with Rails. A guide for developers using the example apps from the RailsApps project. Others may find it helpful as well.
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.
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 Haml
Haml is a popular alternative to the default Rails templating language (“ERB”).
ERB is a templating system that embeds Ruby into an HTML document, similar to ASP, JSP and PHP. It preserves the syntax of HTML and allows Ruby code to be embedded within a pair of <% and %> delimiters. Haml eliminates the <% and %> delimiters and uses indentation to mark the beginning and end of markup so that closing tags are not required.
Haml Advantages and Drawbacks
Haml is intended for “elegant” markup, eliminating the repetitive tags of HTML and integrating conditional logic succinctly. It’s easier to read.
Indentation is significant in Haml, which makes for well-structured code, but failures resulting from indentation errors are annoying when using Haml. An IDE that provides auto-indenting can make Haml easier to use (see HAML in RubyMine).
If you’re working on a team, you may find designers are more comfortable with ERB as it more closely resembles familiar HTML. And Haml will break if everyone on the team is not using tabs or spaces for indentation consistently.
Finally, for someone new to Rails, Haml is one more new thing to learn, which may not be welcome when there’s so much to learn already.
Despite these drawbacks, I like to use Haml because it eliminates superfluous markup and makes view code much easier to read.
Before you start a project with Haml, read advice from Chris Eppstein about how to use Haml.
For more, see a discussion about Haml’s advantages and drawbacks, titled HAML: the unforgivable sin.
Setting Up Haml
Here are instructions for adding Haml to an existing Rails project. You’ll need extra gems in the Gemfile for Haml:
gem 'haml-rails', '>= 0.3.4', :group => :development
Run the gem bundler command:
$ bundle install
With the haml-rails gem, there is no need to modify the application.rb file to accommodate Haml. Any time you generate a controller or scaffold, you’ll get Haml instead of ERB templates. And when your Rails application loads, Haml will be loaded and initialized.
Syntax Highlighting for Haml
You’ll want to add Haml syntax highlighting to your text editor. There are several versions of TextMate bundles for Haml. The most current is the haml-textmate-bundle from Philippe Huibonhoa. TextMate bundles will work with the popular Sublime Text 2 editor as well. If you are using vim, you can install vim plugins for Haml.
Converting HTML to Haml
Most Rails examples and tutorials use ERB. But it is easy to convert ERB to Haml using this website:
Paste your HTML or ERB code into a text field, click convert, and you’ll have clean Haml code, ready to paste in your app views.
If you want to convert an entire Rails application from ERB to Haml, use the html2haml gem. You can use a shell script or write a simple Ruby script to convert a set of files.
Rails Starter Apps Using Haml
If you’d like to start a new project with Haml, you can generate a Rails application set up for Haml. Use the Rails Composer tool to create a new Rails application:
$ rails new myapp -m https://raw.github.com/RailsApps/rails-composer/master/composer.rb
You’ll have a choice of Haml or ERB. Plus the program will give you options for a CSS front-end framework such as Twitter Bootstrap and create a default application layout using HTML5 (see the article HTML5 Boilerplate for Rails Developers).
Creating Haml Applications by Default
The rails new command creates a new Rails application with a default application layout using ERB. If you want to use Haml for every Rails application you build, you can set options for the rails new command in a .railsrc file in your home directory. Here’s how to set up a .railsrc file to use the rails3-haml-html5 template when you create a new Rails application:
# ~/.railsrc -m https://raw.github.com/RailsApps/rails3-application-templates/master/rails3-haml-html5-template.rb
Credits
Brook Riggio wrote a helpful blog post on Haml by Default in a New Rails 3.2 App and initiated work on the rails3-haml-html5 template.
Daniel Kehoe wrote this article for the RailsApps project.
Was this useful to you? Follow me on Twitter:
rails_apps
and tweet some praise. I’d love to know you were helped out by the 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