2014-10-08 08:38:07 +00:00
---
language: haml
2014-10-18 11:25:42 +00:00
filename: learnhaml.haml
2014-10-08 08:38:07 +00:00
contributors:
- ["Simon Neveu", "https://github.com/sneveu"]
2017-09-27 19:13:18 +00:00
- ["Vasiliy Petrov", "https://github.com/Saugardas"]
2014-10-08 08:38:07 +00:00
---
2014-10-18 11:25:42 +00: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-08 22:18:30 +00:00
2014-10-18 11:25:42 +00: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.
2017-09-27 19:13:18 +00:00
```shell
2014-10-18 11:25:42 +00:00
$ haml input_file.haml output_file.html
2017-09-27 19:13:18 +00:00
```
2014-10-08 22:18:30 +00:00
2014-10-08 22:32:22 +00:00
2014-10-08 22:18:30 +00:00
```haml
2014-10-18 11:25:42 +00: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-08 22:18:30 +00:00
/ -------------------------------------------
/ Comments
/ -------------------------------------------
2014-10-18 11:25:42 +00:00
/ This is what a comment looks like in Haml.
2014-10-08 22:18:30 +00:00
/
To write a multi line comment, indent your commented code to be
wrapped by the forward slash
2017-08-23 08:14:39 +00:00
-# This is a silent comment, which means it won't be rendered into the doc at all
2014-10-08 22:18:30 +00:00
/ -------------------------------------------
/ 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 >
2017-09-27 19:13:18 +00:00
/
The div tag is the default element, so it can be omitted.
You can define only class/id using . or #
2017-09-27 19:18:48 +00:00
For example
2017-09-27 19:13:18 +00:00
%div.my_class
%div#my_id
2017-09-27 19:18:48 +00:00
/ Can be written
2017-09-27 19:13:18 +00:00
.my_class
#my_id
2014-10-08 22:18:30 +00:00
2014-10-09 22:13:37 +00:00
/ To add content to a tag, add the text directly after the declaration
2014-10-08 22:18:30 +00:00
%h1 Headline copy
2014-10-09 22:13:37 +00:00
/ To write multiline content, nest it instead
2015-10-08 03:11:24 +00:00
%p
2014-10-09 22:13:37 +00:00
This is a lot of content that we could probably split onto two
separate lines.
2015-10-08 03:11:24 +00:00
/
2014-10-18 11:25:42 +00: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-09 22:13:37 +00:00
%p
& = "Yes & yes"
2014-10-18 11:25:42 +00:00
/ would output 'Yes & yes'
2014-10-08 22:18:30 +00:00
2014-10-09 22:13:37 +00: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-08 22:18:30 +00:00
2014-10-18 11:25:42 +00:00
/ CSS classes can be added to your tags either by chaining .classnames to the tag
2014-10-08 22:18:30 +00:00
%div.foo.bar
2014-10-18 11:25:42 +00:00
/ or as part of a Ruby hash
2014-10-08 22:18:30 +00: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 11:25:42 +00:00
/ To write data-attributes, use the :data key with its value as another hash
2014-10-08 22:18:30 +00:00
%div{:data => {:attribute => 'foo'}}
2017-09-27 19:13:18 +00:00
/ For Ruby version 1.9 or higher you can use Ruby's new hash syntax
%div{ data: { attribute: 'foo' } }
/ Also you can use HTML-style attribute syntax.
%a(href='#' title='bar')
/ And both syntaxes together
%a(href='#'){ title: @my_class .title }
2014-10-08 22:18:30 +00:00
2014-10-09 22:13:37 +00:00
/ -------------------------------------------
/ Inserting Ruby
/ -------------------------------------------
2015-10-08 03:11:24 +00:00
/
2014-10-18 11:25:42 +00:00
To output a Ruby value as the contents of a tag, use an equals sign followed
by the Ruby code
2014-10-09 22:13:37 +00:00
%h1= book.name
%p
= book.author
= book.publisher
2014-10-18 11:25:42 +00:00
/ To run some Ruby code without rendering it to the html, use a hyphen instead
2014-10-09 22:20:19 +00:00
- books = ['book 1', 'book 2', 'book 3']
2014-10-09 22:13:37 +00:00
2014-10-18 11:25:42 +00:00
/ Allowing you to do all sorts of awesome, like Ruby blocks
2014-10-09 22:13:37 +00:00
- books.shuffle.each_with_index do |book, index|
%h1= book
2017-09-27 19:13:18 +00:00
- if book do
2014-10-09 22:13:37 +00:00
%p This is a book
2015-10-10 09:08:50 +00:00
/ Adding ordered / unordered list
%ul
%li
=item1
=item2
2014-10-09 22:13:37 +00:00
/
2014-10-18 11:25:42 +00:00
Again, no need to add the closing tags to the block, even for the Ruby.
2014-10-09 22:13:37 +00:00
Indentation will take care of that for you.
2015-10-10 09:12:30 +00:00
/ -------------------------------------------
/ Inserting Table with bootstrap classes
/ -------------------------------------------
%table.table.table-hover
%thead
%tr
%th Header 1
%th Header 2
%tr
%td Value1
%td value2
%tfoot
%tr
%td
Foot value
2014-10-09 22:13:37 +00:00
/ -------------------------------------------
/ Inline Ruby / Ruby interpolation
/ -------------------------------------------
2014-10-18 11:25:42 +00:00
/ Include a Ruby variable in a line of plain text using #{}
2014-10-09 22:13:37 +00:00
%p Your highest scoring game is #{best_game}
/ -------------------------------------------
/ Filters
/ -------------------------------------------
/
2017-09-27 19:13:18 +00:00
Filters pass the block to another filtering program and return the result in Haml
To use filter type colon and the name of the filter
2014-10-09 22:13:37 +00:00
2017-09-27 19:13:18 +00:00
/ Markdown filter
:markdown
# Header
Text **inside** *block*
/ The code above is compiled into
< h1 > Header< / h1 >
< p > Text < strong > inside< / strong > < em > block< / em > < / p >
/ Javascript filter
2014-10-09 22:20:19 +00:00
:javascript
console.log('This is inline < script > ' ) ;
2014-10-09 22:13:37 +00:00
2017-09-27 19:13:18 +00:00
/ is compiled into
< script >
console.log('This is inline < script > ' ) ;
< / script >
/
There are many types of filters (:markdown, :javascript, :coffee, :css, :ruby and so on)
Also you can define own filter using Haml::Filters
2014-10-09 22:13:37 +00:00
```
## Additional resources
2014-10-09 22:20:19 +00: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-09 22:23:55 +00:00
- [Official Docs ](http://haml.info/docs/yardoc/file.REFERENCE.html ) - If you'd like to go a little deeper.
