= 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
* DRY
* Follows CSS conventions
* Interpolates Ruby code
* Implements Rails templates with the .haml extension
== 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:
#contact
%h1 Eugene Mumbai
%ul.info
%li.login eugene
%li.email eugene@example.com
is compiled to:
== Characters with meaning to Haml
Haml responds to certain special characters. To create an element in the form of
use the % character, immediately followed
by the element name. To specify attributes, include a hash of attributes inside
curly braces. Example:
%one
%meta{:content => 'something'}
%two
%three Hey there
is compiled to:
Hey there
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/ # =>
%meta{:http-equiv => 'Content-Type', :content => 'text/html'}
# =>
HTML div elements are assumed when no %tag is present and the line is
preceeded by either the # or the . characters. This convention
uses familiar CSS semantics: # denotes the id of the element,
. denotes its class name. Example:
#collection
.item
Broken record album
is the same as:
%div{:id => collection}
%div{:class => 'item'}
Broken record album
and is comiled to:
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 # or the
. characters. Example:
#things
%span#rice Chicken Fried
%p.beans The magical fruit
is compiled to:
Chicken Fried
The magical fruit
=== Specifying a document type
When describing xhtml documents with Haml, you can have a document type
generated automatically by including the characters !!! as the first
line in your document. Example:
!!!
%html
%head
%title Myspace
%body
%h1 I am the international space station
%p Sign my guestbook
is compiled to:
Myspace
I am the international space station
Sign my guestbook
== Using Haml as a Rails plugin
Write Rails templates with the .haml extension. Example:
%html
%head
%title= "Teen Wolf (1985)"
%body
#contents
%h1 "A highschooler discovers that he is a werewolf"
%ul.cast
%li "Scott Howard"
%li "Rupert 'Stiles' Stilinski"
%li "Lisa 'Boof' Marconi"
%li "Lewis"
is compiled to:
Teen Wolf (1985)
A highschooler discovers that he is a werewolf
- Scott Howard
- Rupert 'Stiles' Stilinski
- Lisa 'Boof' Marconi
- Lewis
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 = 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"
end
end
file: app/views/movies/index.haml
#content
.title
%h1= @title
= link_to 'Home', home_url
is be compiled to:
---
Copyright (c) 2006 Hampton Catlin