This course will become read-only in the near future. Tell us at community.p2pu.org if that is a problem.

[haml] Jumping In


Lets get started. This task assumes you have a basic knowledge and understanding of Ruby. If you are unfamiliar with Ruby, go to http://tryruby.org/.

If you haven't already, download Ruby from http://ruby-lang.org/ .

You will also need a text editor, if you don't already have one. In Mac OS X, you can use TextEdit; in Windows, you can use Notepad.

First, we need to download the 2 libraries. Open your Terminal or Command Prompt and type gem install haml sass. This will install the latest version of the gems.

Now both of the compilers can be invoked from the command line. Lets write some haml and compile it. First, create a file with a .haml extension and type (using your preferred text editor): 


!!!5
%html{lang: "en"}
  %head
    %title Test
  %body
    #content= "App"

To compile, invoke the command-line compiler by typing 'haml <file>.haml'. After the compilation, the results should be shown on screen. If you want the results to be outputted to a file type: haml <file>.haml <output>.html you can also replace the .html with .erb if your file needs to be dynamic.

Lets dissect this, line by line. The first line declares the <!DOCTYPE> and the suffixed 5 sets it to HTML5. More on available doctypes.

The second line opens the <html> tag and adds the lang attribute using a Ruby hash. Using Ruby hashes is the easy and preferred way to add and populate attributes to tags.

The third line opens the <head> tag.

The fourth line opens the <title> tag and puts the text 'Test' inside it.

The fifth line opens the <body> tag. The compiler also intelligently closes the head here with a </head> before opening the body tag.

Finally, the sixth line creates a div with an id of content and then interprets some very simple Ruby code to add the text "App" to the div. This line of code shows off a few very important features of HAML.

  1. You can specify classes and ids using CSS-style syntax. Here, we use #content to specify an id of "content".
  2. When using divs and specifying an id or class, the %div can be left off. Haml makes an assumption that using divs for content separation is so common that any time an id or class is specified without a tag a div element is assumed to be the container.
  3. You can insert Ruby code, including local variables, by affixing an = to the end of the tag definition. Here, we use #content= "App" to translate a string into text. We could also have done #content= page.content to insert the value of the content property of the page object, or used %title= "Page "+(2*2) to set the title to "Page 4".

As you can see, Haml uses indentation to show nested tags. In this way, Haml is very different from HTML where so-called 'whitespace' is unimportant. If you're not used to using 'significant whitespace', it may take some getting used to, but once you're comfortable with it you'll find it makes coding easier and cleaner.

You'll also notice that tags are defined in haml by prefixing the tag name with a % sign. You can use this to generate any tag: be it %head, %p, %a; HTML5 semantic markup like %article, %aside, %section; or even custom tags like %gee, %whiz, and %neato. The power in this is the flexibility and extensibility. The caution is that the Haml compiler will not do code validation for you to ensure your code is valid markup, so when starting out it's not a bad idea to run your generated code through a validator.

One final thing you may have noticed, and as alluded to in the line-by-line descriptions above, is that Haml will automatically close tags for you when the compiler moves on to the next tag. There are some tags which you will want to be self-closed. You can specify a self-closed tag by adding a / after the tag definition, such as %br/. By default, Haml will auto-self-close the following tags as long as there is no content specified after the definition: meta, img, link, script, br, and hr.

Task Discussion


  • The Smurf   May 24, 2012, 11:36 p.m.

    At the very beginning, we're supposed to type "gem install haml sass".

    My command prompt keeps telling me "gem is not a recognized internal or external command, operable program, or batch file.

    What am I doing wrong?

  • Andrew Steele   July 24, 2012, 1:36 p.m.
    In Reply To:   The Smurf   May 24, 2012, 11:36 p.m.

    Sorry it took so long to respond to this. Chances are good you've already figured it out, but just in case it trips up anyone else: How to Install RubyGems. This also assumes you've got Ruby already installed. If not: How to Setup Ruby and Your Computer to Use Ruby.

  • judytuna   July 24, 2012, 2:38 p.m.
    In Reply To:   The Smurf   May 24, 2012, 11:36 p.m.

    Another great resource is: http://installfest.railsbridge.org/ -- step-by-step instructions to installing Ruby on different operating systems, kept up-to-date by Railsbridge volunteers. You can just go up to the part where you install Ruby, because you won't need Rails. Let me know if you use this and what you think!