Phammable's HAML Syntax

General Form

(indentation)Tag-Definition[ payload]

The document's heirarchy is managed automatically by the file's indentation. Either tabs or spaces may be used, but they must be consistent within each file. The tag definition uses a CSS-like syntax to define an XHTML tag. A single unescaped space character separates the tag definition from the payload; Language operators (specifically, '-' and '=') appended to the tag definition cause Phammable to treat the payload as PHP code. The default behavior is to treat the payload as character data, which is escaped and output.

Whitespace

Whitespace in HAML is significant. You may use spaces or tabs (I prefer tab characters personally), but the following rules should be observed:

Each item's indentation should be one indentation unit greater than its parent.
If spaces are used, the number of leading spaces on the first indented line is used as one indentation unit.
When using tabs, an indentation unit is always exactly one tab character.
Output defaults to two spaces per level of indentation, regardless of indentation units in the original file. This can be changed with the haml_indent_str constant in HAML.php
Whenever a lesser level of indentation is encountered, closing tags will be output until the amount of open indentation matches the current level. This applies both to XHTML elements, and control structures in PHP.

Doctypes

The first line in most phammable documents should be a doctype declaration. This is a triplet of exclamation points followed by shorthand for the document's type. Set this carefully, because future versions of Phammable may send headers to the client based on the declared document type.

Strict: XHTML 1.0 Strict
Transitional: XHTML 1.0 Transitional
Frameset: XHTML 1.0 Frameset
1.1: XHTML 1.1
HTML Strict: HTML 4.01 Strict
HTML Transitional: HTML 4.01 Transitional
HTML Frameset: HTML 4.01 Frameset
HTML: HTML (NO Doctype)

XHTML Doctypes will also cause an XML Open Tag to be output. This will cause errors if PHP's (deprecated) short_open_tags are enabled in php.ini. This site is XHTML 1.1, so all the pages here start with !!! 1.1 . Use the !!! HTML doctype for tag-soup documents and fragments that will be included into larger HTML documents.

HTML / XHTML Operators

These Unary Prefix operators are used to begin identification tokens. Examples include #TopMenu , .selected , %form , or @image.png . They must appear in a contiguous block with no spaces at the beginning of the line.

%: Tag-Name Operator. This specifies the type of the element.
Optional. If omitted, in the presence of other modifiers (ID, Class, Name operators, or an attribute block), defaults to %div
#: Element ID Operator. Specifies the ID of the generated element.
.: Class name Operator. Add the specified class to the generated element. Any number of classes may be added, using the form .class1.class2.class3[...] .
:: Name operator. Eg, %input.text:userName
@: Target URI Operator. This must be the last operator in the tag definition. For some tags, such as %img and %iframe , this will set the src attribute of the tag. For other tags, like %a and %link , it sets href . The URI may not contain unescaped whitespace characters.

Language Operators

Language operators are separated from their payload by a whitespace character. The whitespace character that separates the operator and its payload is ignored, and is not included in the output.

&

Include File (Included at run-time; Interpreter does no checking)

PHP Files are included using include 'file'
Text and HTML Files are included using readFile('file')
HAML Files are included using include haml('file')

No other filetypes are permitted for inclusion.

=

PHP Code, prepend with echo

-

PHP Code, without implicit echo

:=

Literal Output operator; Entities are still escaped, but this allows you to specify text strings that would otherwise be valid HAML syntax and prevent them from being transformed into tags.

Attributes

Attributes are included inside a set of curly braces. Attribute / Value pairs are delimited by a whitespace character. Each pair is of the form name=value . No spaces may appear adjacent to the equal sign. If you need to include spaces in the attribute value, use the form name='value' or name="value" . In this format, spaces may occur inside the quoted string. Attribute names must not be quoted.

To provide a dynamic value for an attribute, use PHP code for the value, quoted with backticks, like input:name{value=`xmlentities($record->name)`} .

For boolean values, which are handled differently between HTML and XHTML, it is recommended that you let Phammable handle their values automatically. The HAML Code %option{selected value=3} MyOption will be output as <option selected value='3'>MyOption</option> for HTML documents, and as <option selected='selected' value='3'>MyOption</option> for XHTML documents.

Flow Control

Flow control in PHP code is managed as well. You can define functions, if-else blocks, for loops and foreach blocks, as well as others, by simply omitting the braces around the loop or function body, and using indentation to delineate it instead. HAML can be mixed in with regular PHP statements.

- function($x, $y)
	%b= "Got $x, $y.\n";
	- return $x + $y;

Alternatively, the entire body can be HAML code.

- if ($showMenu)
	#Menu
		%a@index.haml Main
		%a@logout.php Logout

Additional Features

As part of HAML.php, which is included before the execution of all HAML files, Phammable defines:

xmlentities( string $s , [ boolean $nltobr = false ]);

This function can be used to escape input that may contain XML / XHTML entities. This is very different from PHP's htmlentities function; All the entities replaced by this function are encoded numerically . The second parameter indicates whether newlines in the input string should be replaced by <br /> tags. If necessary, you can use the entify function directly with preg_replace_callback ; It will encode any single UTF-8 characters matched by the expression.

Future Additions

The next goal for phammable is to support inline tag declarations, and inline PHP code. This will probably be implemented by using backtick-quoted code strings for PHP, like `count($records)` . I'll probably use a bound-braces implementation for inline tags, which would look like {%code function(var1,var2);} . The tagtype declaration would be mandatory and would have to come first. One could imagine using them together, like {%b.red You `$winOrLose`} . The biggest difficulty with this approach would be parsing syntax of the form {%a{href=`$item->uri` title=`$item->title`} `$item->name`} . All these things can be accomplished with Phammable currently, but a more beautiful syntax (and shorter files) benefits us all.

Examples

A good example of a complete HAML document can be seen by looking at the code for this site's own main page thereupon .

Foreach Loops

- $entries = $db->getAll("SELECT * FROM Entries ORDER BY timestamp DESC");
#Entries- foreach($entries as $e)
	%tr
		%td= xmlentities($e->name)
		%td= date('Y-m-d H:i', $e->timestamp)
	%tr
		%td{colspan=2}= xmlentities($e->contents)