Skip to content
HTML Abstraction Markup Language - A Markup Haiku
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


= Haml (XHTML Abstraction Markup Language)

HAML is a markup language that's used to cleanly and simply describe the XHTML 
of any web document without the use of inline code. Haml functions as a 
replacement for inline page templating systems such PHP, RHTML, and ASP. 
However, Haml avoids the need for explicitly coding XHTML into the template, 
because it iself is a description of the XHTML, with some code to generate 
dynamic content.

== Features

* Whitespace active
* Well-formatted markup
* Follows CSS conventions
* Interpolates Ruby code
* Implements Rails templates with the .haml extension

== Authors

HAML was originally created by Hampton Catlin (hcatlin). Help with the
Ruby On Rails implementation and much of the documentation by 
Jeff Hardy (packagethief).

If you use this software, you must pay Hampton a compliment. Say something
nice about it. Beyond that, the implementation is licensed under the MIT
License. Ok, fine, I guess that means compliments aren't *required*.

== Formatting

Haml is sensitive to spacing and indentation; it uses nesting to convey
structure. When you want an element to have children, indent the lines below it
using two spaces. Remember, spaces are not the same as tabs. Example:

    %h1 Eugene Mumbai
      %li.login eugene

is compiled to:

  <div id='contact'>
    <h1>Eugene Mumbai</h1>
    <ul class='info'>
      <li class='login'>eugene</li>
      <li class='email'></li>
== Characters with meaning to Haml

Haml responds to certain special characters. To create an element in the form of
<tt><element></element></tt> use the <tt>%</tt> character, immediately followed
by the element name. To specify attributes, include a hash of attributes inside
curly braces. Example:

    %meta{:content => 'something'}/
      %three Hey there

is compiled to:

      <meta content='something' />
      <three>Hey there</three>

Any string is a valid element name; Haml will automatically generate opening and
closing tags for any element. When you want to force the output of a
self-closing tag, use the forward slash character. Example:

  %br/ # => <br />
  %meta{:http-equiv => 'Content-Type', :content => 'text/html'}/
  # => <meta http-equiv='Content-Type' content='text/html' />

HTML div elements are assumed when no <tt>%tag</tt> is present and the line is
preceeded by either the <tt>#</tt> or the <tt>.</tt> characters. This convention
uses familiar CSS semantics: <tt>#</tt> denotes the id of the element,
<tt>.</tt> denotes its class name. Example:

      Broken record album
is the same as:

  %div{:id => collection}
    %div{:class => 'item'}
      Broken record album

and is comiled to:

  <div id='collection'>
    <div class='item'>Broken record album</div>

There is a shortcut when you want to specify either the id or class attributes
of an element: follow the element name with either the <tt>#</tt> or the
<tt>.</tt> characters. Example:

    %span#rice Chicken Fried
    %p.beans The magical fruit

is compiled to:

  <div id='things'>
    <span id='rice'>Chicken Fried</span>
    <p class='beans'>The magical fruit</p>
=== Specifying a document type

When describing xhtml documents with Haml, you can have a document type
generated automatically by including the characters <tt>!!!</tt> as the first
line in your document. Example:

      %title Myspace
      %h1 I am the international space station
      %p Sign my guestbook

is compiled to:

  <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "">
      <h1>I am the international space station</h1>
      <p>Sign my guestbook</p>

== Using Haml as a Rails plugin

Write Rails templates with the .haml extension. Example:

      %title= "Teen Wolf (1985)"
        %h1 "A highschooler discovers that he is a werewolf"
          %li "Scott Howard"
          %li "Rupert 'Stiles' Stilinski"
          %li "Lisa 'Boof' Marconi"
          %li "Lewis"

is compiled to:

      <title>Teen Wolf (1985)</title>
      <div id='contents'>
        <h1>A highschooler discovers that he is a werewolf</h1>
        <ul class='cast'>
          <li>Scott Howard</li>
          <li>Rupert 'Stiles' Stilinski</li>
          <li>Lisa 'Boof' Marconi</li>

You can access instance variables in Haml templates the same way you do in ERb
templates. Helper methods are also available in Haml templates. To specify that
a line should be evaulated as Ruby, use the <tt>=</tt> character at the begining
of a line, or immediately following an element name. The return value of the
method call will be inserted into the stream. Example:

  file: app/controllers/movies_controller.rb

  class MoviesController < ApplicationController
    def index
      @title = "Teen Wolf"

  file: app/views/movies/index.haml

     %h1= @title
     = link_to 'Home', home_url
is be compiled to:

  <div id='content'>
    <div class='title'>
      <h1>Teen Wolf</h1>
      <a href='/'>Home</a>

Copyright (c) 2006 Hampton Catlin
Licensed under the MIT License
Something went wrong with that request. Please try again.