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:
<div class='content'> <h1>Blah!</h1> <p>Blah. Blah blah blah blah, blah blah blah.</p> <p><strong>Blah</strong> blah blah, blah bl-blah blah blah.</
<p><em>Blah</em> blah blah blah.</p> </div>
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 "<pre>" and "<textarea>" tags output by functions, is still available.
Enjoy! - Nathan