2014-10-08 12:38:07 +04:00
---
language: haml
2014-10-18 15:25:42 +04:00
filename: learnhaml.haml
2014-10-08 12:38:07 +04:00
contributors:
- ["Simon Neveu", "https://github.com/sneveu"]
---
2014-10-18 15:25:42 +04:00
Haml is a markup language predominantly used with Ruby that cleanly and simply describes the HTML of any web document without the use of inline code. It is a popular alternative to using Rails templating language (.erb) and allows you to embed Ruby code into your markup.
2014-10-09 02:18:30 +04:00
2014-10-18 15:25:42 +04:00
It aims to reduce repetition in your markup by closing tags for you based on the structure of the indents in your code. The result is markup that is well-structured, DRY, logical, and easier to read.
You can also use Haml on a project independent of Ruby, by installing the Haml gem on your machine and using the command line to convert it to html.
$ haml input_file.haml output_file.html
2014-10-09 02:18:30 +04:00
2014-10-09 02:32:22 +04:00
2014-10-09 02:18:30 +04:00
```haml
2014-10-18 15:25:42 +04:00
/ -------------------------------------------
/ Indenting
/ -------------------------------------------
/
Because of the importance indentation has on how your code is rendered, the
indents should be consistent throughout the document. Any differences in
indentation will throw an error. It's common-practice to use two spaces,
but it's really up to you, as long as they're constant.
2014-10-09 02:18:30 +04:00
/ -------------------------------------------
/ Comments
/ -------------------------------------------
2014-10-18 15:25:42 +04:00
/ This is what a comment looks like in Haml.
2014-10-09 02:18:30 +04:00
/
To write a multi line comment, indent your commented code to be
wrapped by the forward slash
-# This is a silent comment, which means it wont be rendered into the doc at all
/ -------------------------------------------
/ Html elements
/ -------------------------------------------
/ To write your tags, use the percent sign followed by the name of the tag
%body
%header
%nav
/ Notice no closing tags. The above code would output
< body >
< header >
< nav > < / nav >
< / header >
< / body >
2014-10-18 15:25:42 +04:00
/ The div tag is the default element, so they can be written simply like this
2014-10-09 02:18:30 +04:00
.foo
2014-10-10 02:13:37 +04:00
/ To add content to a tag, add the text directly after the declaration
2014-10-09 02:18:30 +04:00
%h1 Headline copy
2014-10-10 02:13:37 +04:00
/ To write multiline content, nest it instead
2015-10-08 06:11:24 +03:00
%p
2014-10-10 02:13:37 +04:00
This is a lot of content that we could probably split onto two
separate lines.
2015-10-08 06:11:24 +03:00
/
2014-10-18 15:25:42 +04:00
You can escape html by using the ampersand and equals sign ( & = ). This
converts html-sensitive characters (& , /, :) into their html encoded
equivalents. For example
2014-10-10 02:13:37 +04:00
%p
& = "Yes & yes"
2014-10-18 15:25:42 +04:00
/ would output 'Yes & yes'
2014-10-09 02:18:30 +04:00
2014-10-10 02:13:37 +04:00
/ You can unescape html by using the bang and equals sign ( != )
%p
!= "This is how you write a paragraph tag < p > < / p > "
/ which would output 'This is how you write a paragraph tag < p > < / p > '
2014-10-09 02:18:30 +04:00
2014-10-18 15:25:42 +04:00
/ CSS classes can be added to your tags either by chaining .classnames to the tag
2014-10-09 02:18:30 +04:00
%div.foo.bar
2014-10-18 15:25:42 +04:00
/ or as part of a Ruby hash
2014-10-09 02:18:30 +04:00
%div{:class => 'foo bar'}
/ Attributes for any tag can be added in the hash
%a{:href => '#', :class => 'bar', :title => 'Bar'}
/ For boolean attributes assign the value 'true'
%input{:selected => true}
2014-10-18 15:25:42 +04:00
/ To write data-attributes, use the :data key with its value as another hash
2014-10-09 02:18:30 +04:00
%div{:data => {:attribute => 'foo'}}
2014-10-10 02:13:37 +04:00
/ -------------------------------------------
/ Inserting Ruby
/ -------------------------------------------
2015-10-08 06:11:24 +03:00
/
2014-10-18 15:25:42 +04:00
To output a Ruby value as the contents of a tag, use an equals sign followed
by the Ruby code
2014-10-10 02:13:37 +04:00
%h1= book.name
%p
= book.author
= book.publisher
2014-10-18 15:25:42 +04:00
/ To run some Ruby code without rendering it to the html, use a hyphen instead
2014-10-10 02:20:19 +04:00
- books = ['book 1', 'book 2', 'book 3']
2014-10-10 02:13:37 +04:00
2014-10-18 15:25:42 +04:00
/ Allowing you to do all sorts of awesome, like Ruby blocks
2014-10-10 02:13:37 +04:00
- books.shuffle.each_with_index do |book, index|
%h1= book
if book do
%p This is a book
/
2014-10-18 15:25:42 +04:00
Again, no need to add the closing tags to the block, even for the Ruby.
2014-10-10 02:13:37 +04:00
Indentation will take care of that for you.
/ -------------------------------------------
/ Inline Ruby / Ruby interpolation
/ -------------------------------------------
2014-10-18 15:25:42 +04:00
/ Include a Ruby variable in a line of plain text using #{}
2014-10-10 02:13:37 +04:00
%p Your highest scoring game is #{best_game}
/ -------------------------------------------
/ Filters
/ -------------------------------------------
/
2015-10-08 06:11:24 +03:00
Use the colon to define Haml filters, one example of a filter you can
2014-10-10 02:13:37 +04:00
use is :javascript, which can be used for writing inline js
2014-10-10 02:20:19 +04:00
:javascript
console.log('This is inline < script > ' ) ;
2014-10-10 02:13:37 +04:00
```
## Additional resources
2014-10-10 02:20:19 +04:00
- [What is HAML? ](http://haml.info/ ) - A good introduction that does a much better job of explaining the benefits of using HAML.
2014-10-10 02:23:55 +04:00
- [Official Docs ](http://haml.info/docs/yardoc/file.REFERENCE.html ) - If you'd like to go a little deeper.
