mirror of
https://github.com/haml/haml.git
synced 2022-11-09 12:33:31 -05:00
213 lines
5.5 KiB
Text
213 lines
5.5 KiB
Text
= 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 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:
|
|
|
|
#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
|