Getting started guide

Installation

HAML.jl is a registered package and can be installed through the usual ]add HAML or using Pkg; Pkg.add("HAML"). It has minimal dependencies.

In-line use

The easiest way to experiment with HAML are haml"..." strings. This is an example of a non-standard string literal and it is implemented through the @haml_str macro. You use it like this:

julia> using HAML

julia> println(haml"%p Hello, world!")
<p>Hello, world!</p>

HAML uses indentation to mark the opening and closing of tags. This makes it possible to write HTML in a very concise way:

julia> link = "https://youtu.be/dQw4w9WgXcQ"
"https://youtu.be/dQw4w9WgXcQ"

julia> haml"""
       !!! 5
       %html
         %body
           %a(href=link) Hello, world!
       """ |> print
<!DOCTYPE html>
<html>
  <body>
    <a href='https://youtu.be/dQw4w9WgXcQ'>Hello, world!</a>
  </body>
</html>

Syntax overview

Use % for tag name, # for the id attribute, . for the class attribute. Use named tuple syntax for other attributes. If % is omitted, we default to div:

julia> haml"""%a(href="/") Click me""" |> println
<a href='/'>Click me</a>

julia> haml"""%a.nav(href="/") Click me too""" |> println
<a class='nav' href='/'>Click me too</a>

julia> haml"""%a#homelink.nav(href="/") Home""" |> println
<a id='homelink' class='nav' href='/'>Home</a>

julia> haml"""#navbar""" |> println
<div id='navbar'></div>

julia> haml""".navitem""" |> println
<div class='navitem'></div>

Use indentation for nesting.
Use - for evaluating Julia code. Use = for including the result of evaluating Julia code:

julia> haml"%p= 2 + 2" |> println
<p>4</p>

julia> haml"""
       %ul
         - for i in 1:2
           %li= i
       """ |> println
<ul>
  <li>1</li>
  <li>2</li>
</ul>

Use $ for interpolation of Julia values into static content:

julia> haml"%p= 2 + 2" |> println
<p>4</p>

julia> haml"""
       %p
         Two and two make $(2 + 2)
         - difficulty = "easy"
         This is $(difficulty)!
       """ |> println
<p>
  Two and two make 4
  This is easy!
</p>

Using HAML templates from files

Use the includehaml function to include a HAML template from a file and make it a function in a certain module.

julia> mktemp() do path, io
           write(io, raw"""
           %p
              Hello from this file! I am running in
              %i= @__MODULE__
              and I received the following parameters:
           %dl
             %dt foo
             %dd= $foo
             %dt bar
             %dd= $bar
           """)
           close(io)
       
           includehaml(Main, :my_first_template, path)
       end
my_first_template (generic function with 6 methods)

julia> Main.my_first_template(foo=42, bar=43) |> print
<p>
   Hello from this file! I am running in
   <i>Main</i>
   and I received the following parameters:
</p>
<dl>
  <dt>foo</dt>
  <dd>42</dd>
  <dt>bar</dt>
  <dd>43</dd>
</dl>

Note how the keyword parameters are available through $foo and $bar.

There is also a render function which takes a file name and immediately renders the result. However, we recommend using includehaml where possible, at the top-level of your module, because Julia will pre-compile the function in this case.