Haml

Haml is a markup language used to describe XHTML. Haml is very easy to read and enables developers to avoid explicitly coding XHTML into their templates. Haml was originally written by Hampton Catlin. Haml also includes a counterpart, Sass, for creating CSS.

Haml also adheres to many of the core principals of Ruby on Rails:

• it is DRY
• it is elegant
• it is easy to read

Consider the following XHTML:

<div id='main'>
  <div class='note'>
    <h2>Quick Notes</h2>
    <ul>
      <li>
        Haml is indented with
        <strong>two spaces *only*</strong>
      </li>
    </ul>
  </div>
</div>

This same XHTML described by Haml would be:

#main
  .note
    %h2 Quick Notes
    %ul
      %li
        Haml is indented with 
        %strong two spaces *only*
     

Install the Haml RubyGem on your work station:

$ gem install haml

current versions are available at Github

After the RubyGem is installed, install the Haml Ruby on Rails plugin.

$ haml --rails /path/to/app
Haml plugin added to /path/to/app

Alternately, plugin installation can be skipped by alternately requiring the Haml RubyGem in your application.

Haml and Sass can be rendered from existing HTML or CSS. After installing the gem and the hpricot dependency, haml, sass, html2haml and css2sass commands are installed. This is helpful for learners who want to see it in action first.

To convert haml to html:

$ haml index.haml > output.html

Likewise, the reverse:

$ html2haml index.html > output.haml

These commands are great for beginners who already know what a div tag looks like and just want to see haml in action.

Use html2haml to help convert old ”.html.erb” views to ”.haml”. Remember to leave any raw HTML files, Rails is only responsible for rendering haml layouts in “views” directories of you application.

The first step to creating a view inside a Rails application using Haml is to replace .html.erb with .haml. For example, the view corresponding to the show action in a students controller would be RAILS_ROOT/app/views/students/show.haml

Haml is simple to use. To reproduce a XHTML tag, simply use %tag. Closing tags is not required and handled via indentation. Indentation must be 2 spaces.

%p hello

produces

<p>hello</p>

and

%div#container
  %p hello

produces

<div id="container">
  <p>hello</p>
</div>

Div tags can be even more easily produced by simply using .class and #id for <div class=“class”> and <div id=“id”> respectively.

#container
  %p hello

also produces

<div id="container">
  <p>hello</p>
</div>

Inserting links or other inline elements into a block of text requires each inline tag to be on its own line. Note that the start of a tag's content must be on a new indented line if there are nested tags or Haml will throw an error. Also note that since a line that starts with a period has significance in Haml, we use a backslash to escape it.

%p
  Here's a link to
  %a{:href => "http://google.com"} Google
  and here's one to
  %a{:href => "http://yahoo.com"} Yahoo
  \.

A fun and neat way to test out Haml is to use the Haml Lab, which will render Haml in your browser.

Haml uses equals (=) to insert the result of Ruby code into the XHTML. This is similar to the way ERb uses <%= %>. For example to replace hello with the value of an instance variable called @student we would use:

#container
  %p= @student

But to say hello to the contents of @student use

#container
  %p= "Hello #{@student}"

To evaluate Ruby code, but not output it, use the hyphen, -.

-@students.each do |student|
  %p== Hello #{student}

This achieves similar results, except saying hello to each student in the @student array. There is no need to close the loop with end, it is handled via indentation.

Notice we did something different. Double equals (==) interpolates Ruby code similarly to the way a single equals interpolates Ruby string.

%p= "Hello #{@student}"

produces the same result as

%p== Hello #{@student}

Haml is very powerful and there is much more to learn.

• Haml homepage.
• Haml Docs.
• Short Haml tutorial.
• Peepcode Edpisode.