= 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). Nathan Weizenbaum (Nex3) contribued the buffered-engine code along with many other enhancements including the silent-line syntax ("-"). 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:

Eugene Mumbai

== Characters with meaning to Haml Various characters, when placed at a certain point in a line, instruct Haml to render different types of things. === XHTML Tags These characters render XHTML tags. ==== % This element is placed at the beginning of a line. It's followed immediately by the name of an element, then optionally by modifiers (see below), a space, and text to be rendered inside the element. It creates an element in the form of . For example: %one %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. ==== {} Brackets represent a Ruby hash that is used for specifying the attributes of an element. It is literally evaluated as a Ruby hash, so logic will work in it, and local variables may be used. Quote characters within the attribute will be replaced by appropriate escape sequences. The hash is placed after the tag is defined. For example: %head{ :name => "doc_head" } %script{ 'type' => "text/" + "javascript", :src => "javascripts/script_#{2 + 7}" } is compiled to: ==== [] Square brackets follow a tag definiton and contain a Ruby object that is used to set the class and id of that tag. The class is set to the object's class (transformed to use underlines rather than camel case), and the id is set to the object's class followed by its id. Because the id of an object is normally an obscure implementation detail, this is most useful for elements that represent instances of Models. For example: # file: app/controllers/users_controller.rb def show @user = CrazyUser.find(15) end # file: app/views/users/show.haml %div[@user] %bar[290]/ Hello! is compiled to:
Hello!
This is based off of DHH's SimplyHelpful syntax as presented at RailsConf Europe 2006. ==== / The forward slash character, when placed at the end of a tag definition, causes the tag to be self-closed. For example: %br/ %meta{:http-equiv => 'Content-Type', :content => 'text/html'}/ is compiled to:
==== . and # The period and sharp sign are borrowed from CSS and used as shortcuts to specify the class and id attributes of an element, respectively. Multiple class attributes can be specified by chaining thier names together with a dot, similiar to the way they are expressed in CSS. They should be placed immediately after the element name and before an optional attributes hash. For example: div#things %span#rice Chicken Fried %p.beans{ :food => 'true' } The magical fruit %h1.class#id La La La is compiled to:
Chicken Fried

The magical fruit

La La La

And, #content .articles .article.title Doogie Howser Comes Out .article.date 2006-11-05 .article.entry Neil Patrick Harris would like to dispel any rumors that he is straight is compiled to:
Doogie Howser Comes Out
2006-11-05
Neil Patrick Harris would like to dispel any rumors that he is straight
==== Implicit Div Elements Because the div element is used so often, it is the default element. If you only define a class and/or id using the . or # syntax, a div element is automatically used. For example: #collection .item .description What a cool item! is the same as: %div{:id => collection} %div{:class => 'item'} %div{:class => 'description'} What a cool item! and is compiled to:
Broken record album
What a cool item!
==== = and ~ = and ~ are placed at the end of a tag definition, after class, id, and attribute declarations. They're just shortcuts for inserting Ruby code into an element. They work the same as = and ~ without a tag; see below for documentation of those. However, if the result is short enough, it is displayed entirely on one line. For example: %p= "hello" %h1~ 1 + 2 is not quite the same as: %p = "hello" %h1 ~ 1 + 2 It's compiled to:

hello

3

In addition, if the tilde character is followed by an indented section of text, the text is rendered on one line using the XHTML newline escape character. For example, .house %pre~ /^^^\ |[] []| |_____| is compiled to: 
 /^^^\
|[] []|
|_____|
=== XHTML Helpers ==== No Special Character If no special character appears at the beginning of a line, it is rendered as plain text. For example: %gee %whiz Wow this is cool! is compiled to: Wow this is cool! ==== !!! When describing XHTML documents with Haml, you can have a document type declaration or an XML prolog generated automatically by including the characters !!!. For example: !!! XML !!! %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

You can also specify the version and type of XHTML after the !!!. XHTML 1.0 Strict, Transitional, and Frameset and XHTML 1.1 are supported. The default version is 1.0 and the default type is Transitional. For example, !!! 1.1 is compiled to: and !!! Strict is compiled to: If you're not using the UTF-8 characterset for your document, you can specify which encoding should appear in the XML prolog in a similar way. For example, !!! XML iso-8859-1 is compiled to: ==== / The forward slash character, when placed at the beginning of a line, wraps all text after it in an HTML comment. For example: %billabong / This is the billabong element I like billabongs! is compiled to: I like billabongs! The forward slash can also wrap indented sections of code. For example: / %p This doesn't render... %div %h1 Because it's commented out! is compiled to: You can also use Interet Explorer conditional comments (about)[http://www.quirksmode.org/css/condcom.html] by enclosing the condition in square brackets after the /. For example: /[if IE] %a{ :href => 'http://www.mozilla.com/en-US/firefox/' } %h1 Get Firefox is compiled to: ==== | The pipe character designates a multiline string. It's placed at the end of a line, and means that all following lines that end with | will be evaluated as though they were on the same line. For example: %whoo %hoo I think this might get | pretty long so I should | probably make it | multiline so it doesn't | look awful. | %p This is short. is compiled to: %hoo I think this might get | pretty long so I should | probably make it | multiline so it doesn't | look awful. | === Ruby evaluators ==== = The equals character is followed by Ruby code, which is evaluated and the output inserted into the document as plain text. For example: %p = ['hi', 'there', 'reader!'].join " " = "yo" is compiled to:

hi there reader! yo

==== ~ The tilde character works the same as the equals character, but the output is modified in such a way that newlines in whitespace-sensitive elements work properly. For example: %foo = "Woah 
  this is   \n
crazy" %foo2 ~ "Woah 
  this is   \n
crazy" is compiled to: Woah 
  this is
crazy Woah 
  this is
crazy ==== - The hyphen character makes the text following it into "silent script", or Ruby script that is evaluated, but not output. It is not reccomended that you use this widely; almost all processing code and logic should be kept to the Controller, the Helper, or partials. For example: - foo = "hello" - foo << " there" - foo << " you!" %p= foo is compiled to:

hello there you!

===== Blocks Like XHTML tags, you don't need to explicity close your Ruby blocks in Haml. Rather, they're automatically closed based on spacing. A block begins whenever the indentation is increased after a silent script command, and ends when the indentation decreases (as long as it's not an +else+ clause or something similar). For example: - (42...47).each do |i| %p= i %p See, I can count! is compiled to:

42

43

44

45

46

Another example: %p - case 2 - when 1 = "1!" - when 2 = "2?" - when 3 = "3." is compiled to:

2?

== Using Haml as a Rails plugin Write Rails templates with the .haml extension. Example: # file: app/views/movies/teen_wolf.haml %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

You can access instance variables in Haml templates the same way you do in ERb templates. Helper methods are also available in Haml templates. 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 may be compiled to:

Teen Wolf

Home
=== Setting Options Options can be set by setting the hash Haml::Template.options from environment.rb. Available options are: [:suppress_eval] Whether or not attribute hashes and Ruby scripts designated by = or ~ should be evaluated. If this is true, said scripts are rendered as empty strings. Defaults to false. [:precompiled] A string containing a precompiled Haml template. If this is passed, template is ignored and no precompilation is done. [:attr_wrapper] The character that should wrap element attributes. This defaults to ' (an apostrophe). Characters of this type within the attributes will be escaped (e.g. by replacing them with ') if the character is an apostrophe or a quotation mark. [:locals] The local variables that will be available within the template. For instance, if :locals is { :foo => "bar" }, then within the template, = foo will produce bar. --- Copyright (c) 2006 Hampton Catlin Licensed under the MIT License