= 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
== Authors
HAML was originally created by Hampton Catlin (hcatlin). Help with the
Ruby On Rails implementation 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:
#contact
%h1 Eugene Mumbai
%ul.info
%li.login eugene
%li.email eugene@example.com
is compiled to:
<div id='contact'>
<h1>Eugene Mumbai</h1>
<ul class='info'>
<li class='login'>eugene</li>
<li class='email'>eugene@example.com</li>
</ul>
</div>
== 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:
%one
%meta{:content => 'something'}/
%two
%three Hey there
is compiled to:
<one>
<two>
<meta content='something' />
<three>Hey there</three>
</two>
</one>
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:
#collection
.item
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>
</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:
#things
%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>
</div>
=== 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:
!!!
%html
%head
%title Myspace
%body
%h1 I am the international space station
%p Sign my guestbook
is compiled to:
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html>
<head>
<title>Myspace</title>
</head>
<body>
<h1>I am the international space station</h1>
<p>Sign my guestbook</p>
</body>
</html>
== 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:
<html>
<head>
<title>Teen Wolf (1985)</title>
</head>
<body>
<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>
<li>Lewis</li>
</ul>
</div>
</body>
</html>
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"
end
end
file: app/views/movies/index.haml
#content
.title
%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>
</div>
</div>
---
Copyright (c) 2006 Hampton Catlin
Licensed under the MIT License
d2e81e242d