[ANN] Haml 1.5!

Rails
1

Haml 1.5 has been released! Download the new version and give it a
try.

For Rails: “./script/plugin install
http://svn.hamptoncatlin.com/svn/haml/tags/stable”
Standalone: “gem install haml”

For those of you who don’t know about Haml, it’s a very snazzy
templating engine that can be used as a replacement for ERb/RHTML.
Rather than just shoving Ruby code into XHTML, Haml actually creates
an abstraction on top of the XHTML document, using whitespace instead
of repetitive start and end tags to denote structure. For more
information, check out the Haml tutorial at
http://haml.hamptoncatlin.com/docs.

So what’s new in 1.5? Along with plenty of bug fixes, version 1.5 adds
various useful and snazzy features to Haml. But the biggest news in
1.5 isn’t a new feature: it’s an entirely new templating engine.

You see, after using Haml for a while, one tends to get used to the
idea that markup can, indeed /should/, be beautiful and concise.
Other, less elegant markup languages begin to seem a little grating.
While working on a stylesheet, one might think “I can right HTML in an
elegant manner. Why can’t I do the same thing with CSS?” Well, we
thought that, too. So we came up with a solution: Syntactically
Awesome StyleSheets, or “Sass.”

Sass is a templating engine for CSS that’s bundled along with Haml
1.5. It allows you to write CSS using the same elegant whitespace-
sensitive style used in Haml. It eliminates the redundancy formerly
inherent in nesting CSS styles, using “namespace” styles such as font-
family and font-weight, re-using the same value, and even writing out
CSS rules. Just stick your “.sass” files in “public/stylesheets/sass”,
and corresponding “.css” files will be created whenever you need them
to be. You can read all about it at
http://haml.hamptoncatlin.com/docs/sass,
but here’s a sample to get you interested:

!main_color = #82fc08

#main
:width 80%
:color = !main_color
:font
:family sans-serif
:size 1.3em

p
:color = !main_color - #404040
:font-size 0.8em

This compiles to

#main {
width: 80%;
color: #82fc08;
font-family: sans-serif;
font-size: 1.3em; }
#main p {
color: #42bc00;
font-size: 0.8em; }

Now, of course Sass is all exciting and wonderful, but what about
those new Haml features I was mentioning? Well, they’re delightful as
well. For instance, Haml now does error handling. Before 1.5, invalid
input wouldn’t cause an error; it would just produce undefined, often
very strange, output. This was the cause of many confusing issues for
many people, even those of us who created Haml. Haml 1.5, however,
checks for syntax errors, and will notify you exactly what went wrong
and where in the document the error occurred, in a way that Rails can
then format as a good old error page.

Haml 1.5 also adds a new type of command: filters, which use the “:”
character followed by the name of the filter. Filters take an indented
block of text and pass it through some sort of text processor,
independent of Haml, and insert the result (as properly indented as
possible) into the Haml document. For example, if you wanted to add
some “humane” markup to your document using Textile, you could do:

.content
:textile
h1. Blah!

 Blah. Blah blah blah blah, blah blah blah.
 *Blah* blah blah, blah bl-blah blah blah.

 _Blah_ blah blah blah.

This would compile to:

Blah!

Blah. Blah blah blah blah, blah blah blah.

Blah blah blah, blah bl-blah blah blah.

Blah blah blah blah.

There are lots of predefined filters, including:

  • :plain doesn’t parse the text at all, allowing you to put “.” and
    other Haml-significant characters at the beginning of a line without
    escaping them with a backslash.
  • :ruby interprets the text as Ruby code, and inserts all output
    printed to stdout into the Haml document.
  • :preserve preserves all whitespace in the text, even at the
    beginning of lines.
  • :erb parses the text with ERb, the engine used for RHTML.
  • :sass parses the text with Sass, of course.
  • :textile and :markdown run the respective text interpreters over
    the text. :textile is only available if the RedCloth gem is
    installed; :markdown is available if either RedCloth or BlueCloth is
    installed.

The introduction of filters also means that the use of the “~”
character to denote a nested block of whitespace-sensitive text is now
entirely redundant. As such, we’ve deprecated it; it’s still usable in
1.5, but a warning will pop up, and it will be removed in the next
version. The :preserve filter should be used instead. The other use of
the “~” character, to preserve the whitespace in “

” and

“” tags output by functions, is still available.


Enjoy!
  • Nathan