# Haml (HTML Abstraction Markup Language) Haml is a markup language that's used to cleanly and simply describe the HTML of any web document, without the use of inline code. Haml functions as a replacement for inline page templating systems such as PHP, ERB, and ASP. However, Haml avoids the need for explicitly coding HTML into the template, because it is actually an abstract description of the HTML, with some code to generate dynamic content. ## Features * Whitespace active * Well-formatted markup * DRY * Follows CSS conventions * Integrates Ruby code * Implements Rails templates with the .haml extension ## Using Haml Haml can be used in three ways: * as a command-line tool, * as a plugin for Ruby on Rails, * and as a standalone Ruby module. The first step for all of these is to install the Haml gem: gem install haml To run Haml from the command line, just use haml input.haml output.html Use `haml --help` for full documentation. To use Haml with Rails, add the following line to the Gemfile: gem "haml" Once it's installed, all view files with the `".html.haml"` extension will be compiled using Haml. You can access instance variables in Haml templates the same way you do in ERB templates. Helper methods are also available in Haml templates. For example: # file: app/controllers/movies_controller.rb class MoviesController < ApplicationController def index @title = "Teen Wolf" end end -# file: app/views/movies/index.html.haml #content .title %h1= @title = link_to 'Home', home_url may be compiled to:

Teen Wolf

Home
### Rails XSS Protection Haml supports Rails' XSS protection scheme, which was introduced in Rails 2.3.5+ and is enabled by default in 3.0.0+. If it's enabled, Haml's {Haml::Options#escape_html `:escape_html`} option is set to `true` by default - like in ERB, all strings printed to a Haml template are escaped by default. Also like ERB, strings marked as HTML safe are not escaped. Haml also has [its own syntax for printing a raw string to the template](#unescaping_html). If the `:escape_html` option is set to false when XSS protection is enabled, Haml doesn't escape Ruby strings by default. However, if a string marked HTML-safe is passed to [Haml's escaping syntax](#escaping_html), it won't be escaped. Finally, all the {Haml::Helpers Haml helpers} that return strings that are known to be HTML safe are marked as such. In addition, string input is escaped unless it's HTML safe. ### Ruby Module Haml can also be used completely separately from Rails and ActionView. To do this, install the gem with RubyGems: gem install haml You can then use it by including the "haml" gem in Ruby code, and using {Haml::Engine} like so: engine = Haml::Engine.new("%p Haml code!") engine.render #=> "

Haml code!

\n" ### Options Haml understands various configuration options that affect its performance and output. In Rails, options can be set by setting the {Haml::Template#options Haml::Template.options} hash in an initializer: # config/initializers/haml.rb Haml::Template.options[:format] = :html5 Outside Rails, you can set them by configuring them globally in Haml::Options.defaults: Haml::Options.defaults[:format] = :html5 Finally, you can also set them by passing an options hash to {Haml::Engine#initialize}. For the complete list of available options, please see {Haml::Options}. ### Encodings When using Ruby 1.9 or later, Haml supports the same sorts of encoding-declaration comments that Ruby does. Although both Ruby and Haml support several different styles, the easiest it just to add `-# coding: encoding-name` at the beginning of the Haml template (it must come before all other lines). This will tell Haml that the template is encoded using the named encoding. By default, the HTML generated by Haml has the same encoding as the Haml template. However, if `Encoding.default_internal` is set, Haml will attempt to use that instead. In addition, the [`:encoding` option](#encoding-option) can be used to specify an output encoding manually. Note that, like Ruby, Haml does not support templates encoded in UTF-16 or UTF-32, since these encodings are not compatible with ASCII. It is possible to use these as the output encoding, though. ## Plain Text A substantial portion of any HTML document is its content, which is plain old text. Any Haml line that's not interpreted as something else is taken to be plain text, and passed through unmodified. For example: %gee %whiz Wow this is cool! is compiled to: Wow this is cool! Note that HTML tags are passed through unmodified as well. If you have some HTML you don't want to convert to Haml, or you're converting a file line-by-line, you can just include it as-is. For example: %p
Blah!
is compiled to:

Blah!

### Escaping: `\` The backslash character escapes the first character of a line, allowing use of otherwise interpreted characters as plain text. For example: %title = @title \= @title is compiled to: MyPage = @title ## HTML Elements ### Element Name: `%` The percent character 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. ### Attributes: `{}` or `()` {#attributes} 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: %html{:xmlns => "http://www.w3.org/1999/xhtml", "xml:lang" => "en", :lang => "en"} is compiled to: Attribute hashes can also be stretched out over multiple lines to accommodate many attributes. However, newlines may only be placed immediately after commas. For example: %script{:type => "text/javascript", :src => "javascripts/script_#{2 + 7}"} is compiled to: #### `:class` and `:id` Attributes {#class-and-id-attributes} The `:class` and `:id` attributes can also be specified as a Ruby array whose elements will be joined together. A `:class` array is joined with `" "` and an `:id` array is joined with `"_"`. For example: %div{:id => [@item.type, @item.number], :class => [@item.type, @item.urgency]} is equivalent to: %div{:id => "#{@item.type}_#{@item.number}", :class => "#{@item.type} #{@item.urgency}"} The array will first be flattened and any elements that do not test as true will be removed. The remaining elements will be converted to strings. For example: %div{:class => [@item.type, @item == @sortcol && [:sort, @sortdir]] } Contents could render as any of:
Contents
Contents
Contents
Contents
depending on whether `@item.type` is `"numeric"` or `nil`, whether `@item == @sortcol`, and whether `@sortdir` is `"ascending"` or `"descending"`. If a single value is specified and it evaluates to false it is ignored; otherwise it gets converted to a string. For example: .item{:class => @item.is_empty? && "empty"} could render as either of: class="item" class="item empty" #### HTML-style Attributes: `()` Haml also supports a terser, less Ruby-specific attribute syntax based on HTML's attributes. These are used with parentheses instead of brackets, like so: %html(xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en") Ruby variables can be used by omitting the quotes. Local variables or instance variables can be used. For example: %a(title=@title href=href) Stuff This is the same as: %a{:title => @title, :href => href} Stuff Because there are no commas separating attributes, though, more complicated expressions aren't allowed. For those you'll have to use the `{}` syntax. You can, however, use both syntaxes together: %a(title=@title){:href => @link.href} Stuff You can also use `#{}` interpolation to insert complicated expressions in a HTML-style attribute: %span(class="widget_#{@widget.number}") HTML-style attributes can be stretched across multiple lines just like hash-style attributes: %script(type="text/javascript" src="javascripts/script_#{2 + 7}") #### Ruby 1.9-style Hashes On Ruby 1.9, Haml also supports Ruby's new hash syntax: %a{title: @title, href: href} Stuff #### Attribute Methods A Ruby method call that returns a hash can be substituted for the hash contents. For example, {Haml::Helpers} defines the following method: def html_attrs(lang = 'en-US') {:xmlns => "http://www.w3.org/1999/xhtml", 'xml:lang' => lang, :lang => lang} end This can then be used in Haml, like so: %html{html_attrs('fr-fr')} This is compiled to: You can use as many such attribute methods as you want by separating them with commas, like a Ruby argument list. All the hashes will me merged together, from left to right. For example, if you defined def hash1 {:bread => 'white', :filling => 'peanut butter and jelly'} end def hash2 {:bread => 'whole wheat'} end then %sandwich{hash1, hash2, :delicious => 'true'}/ would compile to: Note that the Haml attributes list has the same syntax as a Ruby method call. This means that any attribute methods must come before the hash literal. Attribute methods aren't supported for HTML-style attributes. #### Boolean Attributes Some attributes, such as "checked" for `input` tags or "selected" for `option` tags, are "boolean" in the sense that their values don't matter - it only matters whether or not they're present. In HTML (but not XHTML), these attributes can be written as To do this in Haml using hash-style attributes, just assign a Ruby `true` value to the attribute: %input{:selected => true} In XHTML, the only valid value for these attributes is the name of the attribute. Thus this will render in XHTML as To set these attributes to false, simply assign them to a Ruby false value. In both XHTML and HTML, %input{:selected => false} will just render as: HTML-style boolean attributes can be written just like HTML: %input(selected) or using `true` and `false`: %input(selected=true) #### HTML5 Custom Data Attributes HTML5 allows for adding [custom non-visible data attributes](http://www.whatwg.org/specs/web-apps/current-work/multipage/elements.html#embedding-custom-non-visible-data) to elements using attribute names beginning with `data-`. Custom data attributes can be used in Haml by using the key `:data` with a Hash value in an attribute hash. Each of the key/value pairs in the Hash will be transformed into a custom data attribute. For example: %a{:href=>"/posts", :data => {:author_id => 123}} Posts By Author will render as: Posts By Author Notice that the underscore in `author_id` was replaced by a hyphen. If you wish to suppress this behavior, you can set Haml's [`:hyphenate_data_attrs` option](#hyphenate_data_attrs-option) to `false`, and the output will be rendered as: Posts By Author ### Class and ID: `.` and `#` The period and pound sign are borrowed from CSS. They are used as shortcuts to specify the `class` and `id` attributes of an element, respectively. Multiple class names can be specified in a similar way to CSS, by chaining the class names together with periods. They are placed immediately after the tag and before an attributes hash. For example: %div#things %span#rice Chicken Fried %p.beans{ :food => 'true' } The magical fruit %h1.class.otherclass#id La La La is compiled to:
Chicken Fried

The magical fruit

La La La

And, %div#content %div.articles %div.article.title Doogie Howser Comes Out %div.article.date 2006-11-05 %div.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
These shortcuts can be combined with long-hand attributes; the two values will be merged together as though they were all placed in an array (see [the documentation on `:class` and `:id` attributes](#class-and-id-attributes)). For example: %div#Article.article.entry{:id => @article.number, :class => @article.visibility} is equivalent to %div{:id => ['Article', @article.number], :class => ['article', 'entry', @article.visibility]} Gabba Hey and could compile to:
Gabba Hey
#### Implicit Div Elements Because divs are used so often, they're the default elements. If you only define a class and/or id using `.` or `#`, a div is automatically used. For example: #collection .item .description What a cool item! is the same as: %div#collection %div.item %div.description What a cool item! and is compiled to:
What a cool item!
### Self-Closing Tags: `/` 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:
Some tags are automatically closed, as long as they have no content. `meta`, `img`, `link`, `script`, `br`, and `hr` tags are closed by default. This list can be customized by setting the [`:autoclose`](#autoclose-option) option. For example: %br %meta{'http-equiv' => 'Content-Type', :content => 'text/html'} is also compiled to:
### Whitespace Removal: `>` and `<` `>` and `<` give you more control over the whitespace near a tag. `>` will remove all whitespace surrounding a tag, while `<` will remove all whitespace immediately within a tag. You can think of them as alligators eating the whitespace: `>` faces out of the tag and eats the whitespace on the outside, and `<` faces into the tag and eats the whitespace on the inside. They're placed at the end of a tag definition, after class, id, and attribute declarations but before `/` or `=`. For example: %blockquote< %div Foo! is compiled to:
Foo!
And: %img %img> %img is compiled to: And: %p<= "Foo\nBar" is compiled to:

Foo Bar

And finally: %img %pre>< foo bar %img is compiled to:
foo
    bar
### Object Reference: `[]` Square brackets follow a tag definition 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 the value of its `#to_key` or `#id` method (in that order). This is most useful for elements that represent instances of Active Model models. Additionally, the second argument (if present) will be used as a prefix for both the id and class attributes. For example: # file: app/controllers/users_controller.rb def show @user = CrazyUser.find(15) end -# file: app/views/users/show.haml %div[@user, :greeting] %bar[290]/ Hello! is compiled to:
Hello!
If you require that the class be something other than the underscored object's class, you can implement the `haml_object_ref` method on the object. # file: app/models/crazy_user.rb class CrazyUser < ActiveRecord::Base def haml_object_ref "a_crazy_user" end end -# file: app/views/users/show.haml %div[@user] Hello! is compiled to:
Hello!
## Doctype: `!!!` When describing HTML documents with Haml, you can have a document type or 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 specific doctype after the `!!!` When the [`:format`](#format-option) is set to `:xhtml`. The following doctypes are supported: `!!!` : XHTML 1.0 Transitional
`` `!!! Strict` : XHTML 1.0 Strict
`` `!!! Frameset` : XHTML 1.0 Frameset
`` `!!! 5` : XHTML 5
``
`!!! 1.1` : XHTML 1.1
`` `!!! Basic` : XHTML Basic 1.1
` ` `!!! Mobile` : XHTML Mobile 1.2
`` `!!! RDFa` : XHTML+RDFa 1.0
`` When the [`:format`](#format-option) option is set to `:html4`, the following doctypes are supported: `!!!` : HTML 4.01 Transitional
`` `!!! Strict` : HTML 4.01 Strict
`` `!!! Frameset` : HTML 4.01 Frameset
`` When the [`:format`](#format-option) option is set to `:html5`, `!!!` is always ``. If you're not using the UTF-8 character set 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: If the mime_type of the template being rendered is `text/xml` then a format of `:xhtml` will be used even if the global output format is set to `:html4` or `:html5`. ## Comments Haml supports two sorts of comments: those that show up in the HTML output and those that don't. ### HTML Comments: `/` The forward slash character, when placed at the beginning of a line, wraps all text after it in an HTML comment. For example: %peanutbutterjelly / This is the peanutbutterjelly element I like sandwiches! is compiled to: I like sandwiches! 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: #### Conditional Comments: `/[]` You can also use [Internet Explorer conditional comments](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: ### Haml Comments: `-#` The hyphen followed immediately by the pound sign signifies a silent comment. Any text following this isn't rendered in the resulting document at all. For example: %p foo -# This is a comment %p bar is compiled to:

foo

bar

You can also nest text beneath a silent comment. None of this text will be rendered. For example: %p foo -# This won't be displayed Nor will this Nor will this. %p bar is compiled to:

foo

bar

## Ruby Evaluation ### Inserting Ruby: `=` The equals character is followed by Ruby code. This code is evaluated and the output is inserted into the document. For example: %p = ['hi', 'there', 'reader!'].join " " = "yo" is compiled to:

hi there reader! yo

If the [`:escape_html`](#escape_html-option) option is set, `=` will sanitize any HTML-sensitive characters generated by the script. For example: = '' would be compiled to <script>alert("I'm evil!");</script> `=` can also be used at the end of a tag to insert Ruby code within that tag. For example: %p= "hello" would be compiled to:

hello

A line of Ruby code can be stretched over multiple lines as long as each line but the last ends with a comma. For example: = link_to_remote "Add to cart", :url => { :action => "add", :id => product.id }, :update => { :success => "cart", :failure => "error" } Note that it's illegal to nest code within a tag that ends with `=`. ### Running Ruby: `-` The hyphen character is also followed by Ruby code. This code is evaluated but *not* inserted into the document. **It is not recommended that you use this widely; almost all processing code and logic should be restricted to Controllers, Helpers, or partials.** For example: - foo = "hello" - foo << " there" - foo << " you!" %p= foo is compiled to:

hello there you!

A line of Ruby code can be stretched over multiple lines as long as each line but the last ends with a comma. For example: - links = {:home => "/", :docs => "/docs", :about => "/about"} #### Ruby Blocks Ruby blocks, like XHTML tags, don't need to be explicitly closed in Haml. Rather, they're automatically closed, based on indentation. A block begins whenever the indentation is increased after a Ruby evaluation command. It 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

See, I can count!

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

2?

### Whitespace Preservation: `~` {#tilde} `~` works just like `=`, except that it runs {Haml::Helpers#find\_and\_preserve} on its input. For example, ~ "Foo\n
Bar\nBaz
" is the same as: = find_and_preserve("Foo\n
Bar\nBaz
") and is compiled to: Foo
Bar
Baz
See also [Whitespace Preservation](#whitespace_preservation). ### Ruby Interpolation: `#{}` Ruby code can also be interpolated within plain text using `#{}`, similarly to Ruby string interpolation. For example, %p This is #{h quality} cake! is the same as %p= "This is the #{h quality} cake!" and might compile to:

This is scrumptious cake!

Backslashes can be used to escape `#{}` strings, but they don't act as escapes anywhere else in the string. For example: %p Look at \\#{h word} lack of backslash: \#{foo} And yon presence thereof: \{foo} might compile to:

Look at \yon lack of backslash: #{foo} And yon presence thereof: \{foo}

Interpolation can also be used within [filters](#filters). For example: :javascript $(document).ready(function() { alert(#{@message.to_json}); }); might compile to: ### Escaping HTML: `&=` {#escaping_html} An ampersand followed by one or two equals characters evaluates Ruby code just like the equals without the ampersand, but sanitizes any HTML-sensitive characters in the result of the code. For example: &= "I like cheese & crackers" compiles to I like cheese & crackers If the {Haml::Options#escape_html `:escape_html`} option is set, `&=` behaves identically to `=`. `&` can also be used on its own so that `#{}` interpolation is escaped. For example, & I like #{"cheese & crackers"} compiles to: I like cheese & crackers ### Unescaping HTML: `!=` {#unescaping_html} An exclamation mark followed by one or two equals characters evaluates Ruby code just like the equals would, but never sanitizes the HTML. By default, the single equals doesn't sanitize HTML either. However, if the {Haml::Options#escape_html `:escape_html`} option is set, `=` will sanitize the HTML, but `!=` still won't. For example, if `:escape_html` is set: = "I feel !" != "I feel !" compiles to I feel <strong>! I feel ! `!` can also be used on its own so that `#{}` interpolation is unescaped. For example, ! I feel #{""}! compiles to I feel ! ## Filters {#filters} The colon character designates a filter. This allows you to pass an indented block of text as input to another filtering program and add the result to the output of Haml. The syntax is simply a colon followed by the name of the filter. For example: %p :markdown # Greetings Hello, *World* is compiled to:

Greetings

Hello, World

Filters can have Ruby code interpolated with `#{}`. For example: - flavor = "raspberry" #content :textile I *really* prefer _#{flavor}_ jam. is compiled to

I really prefer raspberry jam.

Currently, filters ignore the {Haml::Options#escape_html `:escape_html`} option. This means that `#{}` interpolation within filters is never HTML-escaped. The functionality of some filters such as Markdown can be provided by many different libraries. Usually you don't have to worry about this - you can just load the gem of your choice and Haml will automatically use it. However in some cases you may want to make Haml explicitly use a specific gem to be used by a filter. In these cases you can do this via Tilt, the library Haml uses to implement many of its filters: Tilt.prefer Tilt::RedCarpetTemplate See the [Tilt documentation](https://github.com/rtomayko/tilt#fallback-mode) for more info. Haml comes with the following filters defined: {#cdata-filter} ### `:cdata` Surrounds the filtered text with CDATA tags. {#coffee-filter} ### `:coffee` Compiles the filtered text to Javascript using Cofeescript. You can also reference this filter as `:coffeescript`. This filter is implemented using Tilt. {#css-filter} ### `:css` Surrounds the filtered text with `