Haml parser reference

User guide

What is Haml?

This is the best Haml definition:

Haml takes your gross, ugly templates and replaces them with veritable Haiku.

Haml is the next step in generating views in your Rails (also in PHP) application. Haml is a refreshing take that is meant to free us from the shitty templating languages we have gotten used to.

Haml is based on one primary principal. Markup should be beautiful.

I'm not Haml author, I only implemented Haml in PHP. Why? I tested a lot of templating system like Smarty, PHP TAL, clean PHP, but all has one problem - too many unreadable code.

Comparision

Read this examples. Which is simplier, cleaner, shorten and more beautiful?? Haml!

PHP example

<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd">
<html>
  <head>
    <meta http-equiv="Content-Type" content="application/xhtml+xml;charset=utf-8" />
    <?php if ($title) { ?>
      <title><?php echo $title; ?></title>
    <?php } else { ?>
      <title><?php echo $pagename; ?></title>
    <?php } ?>
  </head>
  <body>
    <div id="header">
      <h1><?php echo $pagename; ?></h1>
      <?php if ($slogan) { ?>
        <span><?php echo $slogan; ?></span>
      <?php } ?>
    </div>
    <div id="content">
      <table class="config list">
        <tr><th>ID</th><th>Name</th><th>Value</th></tr>
        <?php foreach ($config as $c) { ?>
          <tr class="<?php echo ($class = forClassName($c)); ?>"
                 id="<?php echo "$class_{$c->ID}"; ?>">
            <td><?php echo $c->ID; ?></td>
            <td><?php echo $c->name; ?></td>
            <td><?php echo $c->value; ?></td>
          </tr>
        <?php } ?>
      </table>
    </div>
    <div id="footer">
      <span class="author">Random Hacker</span>
    </div>
  </body>
</html>

phpHaml example

!!! 1.1
%html
  %head
    %meta{ :http-equiv => 'Content-Type', :content => 'application/xhtml+xml;charset=utf-8' }
    - if ($title)
      %title= $title
    - else
      %title= $pagename
  %body
    #header
      %h1 Example page
      - if ($slogan)
        %span= $slogan
    #content
      %table.config.list
        %tr
          %th ID
          %th Name
          %th Value
        - foreach ($config as $c)
          %tr[$c]
            %td= $c->ID
            %td= $c->name
            %td= $c->value
    #footer
      %span.author Random Hacker

License

phpHaml is distributed under MIT License (X11 License).

Copyright © 2007 Amadeusz Jasak and Haml team.

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

How obtain phpHaml?

Stable release

You can download latest stable release of phpHaml from project download page.

Developer release

Of course if you want to obtain developer release (unstable) you can use Subversion repository.

Haml language reference

I'm not providing full Haml language reference. Please use language reference on Haml author's page.

HamlParser class reference

`object __construct([string path, [mixed compile]])`

The constructor. Create the instance of HamlParser.

Arguments

path
Path to directory with templates. Path must exists and can't ends with slash (/).: compile
If compile == false then path for compiled templates is same as source path and templates are compiled on every request. If compile is string then compile = path to compiled templates and templates are compiled only if source changed.

`string __toString()`

Render current template and return it.

`object append(array data)`

Sets the template variables from associative array and return object instance.

Arguments

data
Associative array where keys are variables names and values are variables values.

`object assign(string name, mixed value)`

Sets the template variable and return object instance.

Arguments

name
Name of variable.: value
Value of variable.

`object clearCompiled()`

Removes all compiled templates (*.hphp) from temporary directory and return object instance.

`object clearVariables()`

Clear templates variables and return object instance.

`void display([string filename])`

Display current template or template from filename.

Arguments

filename
Optional filename or full file path to template.

`string fetch([string filename])`

Fetch (return compiled) current template or template from filename.

Arguments

filename
Optional filename or full file path to template.

`string getFilename(string name)`

Return filename used for including. You can override this method.

Arguments

name
Name to file (view) to include.

`array getVariables()`

Return associative array of variables assigned to template.

`string render()`

Similar functionality as fetch().

`object setFile(string filename)`

Sets template filename and return object instance.

Arguments

filename
Real path or file in templates directory.

`object setPath(string path)`

Sets path to templates and return object instance.

Arguments

path
Path to templates without ending slash (/).

`object setSource(string source)`

Sets Haml source and return object instance.

Arguments

source
Haml source (can be multiline or one line).

`object setTmp(string path)`

Sets path to compiled templates and return object instance.

Arguments

path
Path to compiled templates.

`object registerBlock(callable block, string name)`

Arguments

block
The processing function. Argument of it is text block data, callable must return processed data.: name
Name of processing block used in templates

`object unregisterBlock(string name)`

Unregister (delete) text processing block

Arguments

name
Name of processing block to unregister

`object registerFilter(callable filter, string name)`

Arguments

filter
The processing function. Argument of it is compiled template, callable must return processed compiled template.: name
Name of output filter

`object unregisterFilter(string name)`

Unregister (delete) output filter

Arguments

name
Name of output filter to unregister

Conclusion

Thanks for reading this reference. If you want contact please write to Amadeusz Jasak. If you can please donate project.

Thanks for project hosting.