====== Haml ======

[[http://haml-lang.com/|Haml]] is a markup language used to describe XHTML. Haml is very easy to read and enables developers to avoid explicitly coding XHTML into their templates.  Haml was originally written by [[http://hamptoncatlin.com/|Hampton Catlin]].  Haml also includes a counterpart, [[http://sass-lang.com|Sass]], for creating CSS.

Haml also adheres to many of the core [[getting-started:overview:tenets|principals]] of Ruby on Rails:
  *it is [[http://en.wikipedia.org/wiki/Don't_repeat_yourself|DRY]]
  *it is elegant
  *it is easy to read

Consider the following XHTML:
<code html><div id='main'>
  <div class='note'>
    <h2>Quick Notes</h2>
    <ul>
      <li>
        Haml is indented with
        <strong>two spaces *only*</strong>
      </li>
    </ul>
  </div>
</div></code>
This same XHTML described by Haml would be:
<code>#main
  .note
    %h2 Quick Notes
    %ul
      %li
        Haml is indented with 
        %strong two spaces *only*
     </code>

=====Installation=====

Install the Haml RubyGem on your work station:
<code>$ gem install haml</code>
{{:getting-started:installation:information.png|}}current versions are available at [[http://github.com/nex3/haml/tree/master|Github]]

After the RubyGem is installed, install the Haml Ruby on Rails plugin.
<code>$ haml --rails /path/to/app
Haml plugin added to /path/to/app</code>
{{:getting-started:installation:information.png|}}Alternately, plugin installation can be skipped by alternately requiring the Haml RubyGem in your application.

=====Basic Usage=====

===Command line===

Haml and Sass can be rendered from existing HTML or CSS. After installing the gem and the hpricot dependency, haml, sass, html2haml and css2sass commands are installed. This is helpful for learners who want to see it in action first.

To convert haml to html:

<code>$ haml index.haml > output.html</code>

Likewise, the reverse:

<code>$ html2haml index.html > output.haml</code>

These commands are great for beginners who already know what a div tag looks like and just want to see haml in action.

{{:getting-started:installation:information.png|}}Use html2haml to help convert old ".html.erb" views to ".haml".  Remember to leave any raw HTML files, Rails is only responsible for rendering haml layouts in "views" directories of you application. 

=== Inside Rails ===

The first step to creating a view inside a Rails application using Haml is to replace ''.html.erb'' with ''.haml''.  For example, the view corresponding to the ''show'' action in a ''students'' controller would be ''RAILS_ROOT/app/views/students/show.haml''

Haml is simple to use.  To reproduce a XHTML tag, simply use ''%tag''.  Closing tags is not required and handled via indentation.  Indentation must be 2 spaces.
<code>%p hello</code>
produces
<code html><p>hello</p></code> 
and 
<code>%div#container
  %p hello</code>
produces
<code html><div id="container">
  <p>hello</p>
</div>
</code>
''Div'' tags can be even more easily produced by simply using ''.class'' and ''#id'' for ''<div class="class">'' and ''<div id="id">'' respectively.
<code>#container
  %p hello
</code> 
also produces
<code html><div id="container">
  <p>hello</p>
</div>
</code>

Inserting links or other inline elements into a block of text requires each inline tag to be on its own line. Note that the start of a tag's content must be on a new indented line if there are nested tags or Haml will throw an error. Also note that since a line that starts with a period has significance in Haml, we use a backslash to escape it.
<code>%p
  Here's a link to
  %a{:href => "http://google.com"} Google
  and here's one to
  %a{:href => "http://yahoo.com"} Yahoo
  \.
</code>

{{:getting-started:installation:information.png|}}A fun and neat way to test out Haml is to use the [[http://lab.hamptoncatlin.com/play/with/haml|Haml Lab]], which will render Haml in your browser.

=====Ruby Code=====

Haml uses equals (''='') to insert the result of Ruby code into the XHTML.  This is similar to the way ERb uses ''<%= %>''.
For example to replace ''hello'' with the value of an instance variable called ''@student'' we would use:
<code>#container
  %p= @student
</code> 
But to say ''hello'' to the contents of ''@student'' use
<code>#container
  %p= "Hello #{@student}"
</code>
To evaluate Ruby code, but not output it, use the hyphen, ''-''.
<code>-@students.each do |student|
  %p== Hello #{student}
</code>
This achieves similar results, except saying ''hello'' to each student in the ''@student'' array.  There is no need to close the loop with ''end'', it is handled via indentation.

Notice we did something different. Double equals (''=='') interpolates Ruby code similarly to the way a single equals interpolates Ruby string.
<code>%p= "Hello #{@student}"</code>
produces the same result as
<code>%p== Hello #{@student}</code>

=====Further Reading=====

Haml is very powerful and there is much more to learn. 
  *[[http://haml-lang.com/|Haml homepage]].
  *[[http://haml-lang.com/docs.html|Haml Docs]].
  *[[http://haml-lang.com/tutorial.html|Short Haml tutorial]].
  *[[https://peepcode.com/products/haml-and-sass|Peepcode Episode]].