Find file
Fetching contributors…
Cannot retrieve contributors at this time
283 lines (179 sloc) 7.08 KB

HamlPy Reference


easy_install hamlpy


To simply output the conversion to your console:

hamlpy inputFile.hamlpy

Or you can have it dump right into a file:

hamlpy inputFile.hamlpy outputFile.html

There is also a script which will watch for changed hamlpy extensions and regenerate the html as they are edited:

hamlpy-watcher <watch-folder>

A note about output

All of the following examples will show the HTML output nicely formatted. Currently HamlPy actually outputs it with all white space stripped but the examples are formatted this way just for easy reading.

Plain Text

Any line that is not interpreted as something else will be taken as plain text and outputted unmodified. For example:

        Wow this is cool!

is compiled to:

        Wow this is cool!

HTML Elements

Element Name: %

The percent character placed at the beginning of the line will then be followed by the name of the element, then optionally modifiers (see below), a space, and text to be rendered inside the element. It creates an element in the form of . For example:

        %three Hey there

is compiled to:

        <three>Hey there</three>

Any string is a valid element name and a opening and closing tag will automatically be generated.

Attributes: {}

Brackets represent a Python dictionary that is used for specifying the attributes of an element. The dictionary is placed after the tag is defined. For example:

%html{'xmlns':'', 'xml:lang':'en', 'lang':'en'}

is compiled to:

<html xmlns='' xml:lang='en' lang='en'></html>

'class' and 'id' attributes

The 'class' and 'id' attributes can also be specified as a Python tuple whose elements will be joined together. A 'class' tuple will be joined with " " and an 'id' tuple is joined with "_". For example:

%div{'id': ('article', '3'), 'class': ('newest', 'urgent')} Content

is compiled to:

<div id='article_3' class='newest urgent'>Content</div>

Class and ID: . and

The period and pound sign are borrowed from CSS. They are used as shortcuts to specify the class and id attributes of an element, respectively. Multiple class names can be specified by chaining class names together with periods. They are placed immediately after a tag and before an attribute dictionary. For example:

    %span#rice Chicken Fried
    %p.beans{'food':'true'} The magical fruit
    %h1#id.class.otherclass La La La

is compiled to:

<div id='things'>
    <span id='rice'>Chiken Fried</span>
    <p class='beans' food='true'>The magical fruit</p>
    <h1 id='id' class='class otherclass'>La La La</h1>


        %div.article.title Doogie Howser Comes Out 2006-11-05
            Neil Patrick Harris would like to dispel any rumors that he is straight

is compiled to:

<div id='content'>
    <div class='articles'>
        <div class='article title'>Doogie Howser Comes Out</div>
        <div class='article date'>2006-11-05</div>
        <div class='article entry'>
            Neil Patrick Harris would like to dispel any rumors that he is straight

These shortcuts can be combined with the attribute dictionary and they will be combined as if they were all put inside a tuple. For example:

%div#Article.article.entry{'id':'1', class='visible'} Booyaka

is equivalent to:

%div{'id':('Article','1'), 'class':('article','entry','visible')} Booyaka

and would compile to:

<div id='Article_1' class='article entry visible'>Booyaka</div>

Implicit div elements

Because divs are used so often, they are the default element. If you only define a class and/or id using . or # the %div will be implied. For example:

        .description What a cool item!

will compile to:

<div id='collection'>
    <div id='item'>
        <div id='description'>What a cool item!</div>

Self-Closing Tags: /

The forward slash character, when placed at the end of a tag definition, causes the tag to be self-closed. For example:

%meta{'http-equiv':'Content-Type', 'content':'text/html'}/

will compile to:

<br />
<meta http-quiv='Content-Type' content='text/html' />

Some tags are automatically closed, as long as they have no content. meta, img, link, script, br and hr tags are automatically closed. For example:

%meta{'http-equiv':'Content-Type', 'content':'text/html'}

will compile to:

<br />
<meta http-quiv='Content-Type' content='text/html' />


There are two types of comments supported. Those that show up in the HTML and those that don't.

HTML Comments /

The forward slash character, when placed at the beginning of a line, wraps all the text after it in an HTML comment. For example:

    / This is the peanutbutterjelly element
    I like sandwiches!

is compiled to:

    <!-- This is the peanutbutterjelly element -->
    I like sandwiches!

The forward slash can also wrap indented sections of code. For example:

    %p This doesn't render
        %h1 Because it's commented out!

is compiled to:

    <p>This doesn't render</p>
        <h1>Because it's commented out!</h1>

HamlPy Comments: -

The hyphen followed immediately by the pound sign signifies a silent comment. Any text following this isn't rendered during compilation at all. For example:

%p foo
-# Some comment
%p bar

is compiled to:


Django Specific Elements

The key difference in HamlPy from Haml is the support for Django elements. The syntax for ruby evaluation is borrowed from Haml and instead outputs Django tags and variables.

Django Variables: =

A line starting with an equal sign followed by a space and then content is evaluated as a Django variable. For example:

        = story.teaser

is compiled to:

<div class='article'>
    <div class='preview'>
        {{ story.teaser }}

A Django variable can also be used as content for any HTML element by placing an equals sign as the last character before the space and content. For example:

    %a{'href'='stories/1'}= story.teaser

is compiled to:

    <a href='stories/1'>{{ story.teaser }}</a>

Django Tags: -

The hypen character at the start of the line followed by a space and a Django tag will be inserted as a Django tag. For example:

- block content
    %h1= section.title

    - for dog in dog_list

is compiled to:

{% block content %}
    <h1>{{ section.title }}</h1>

    {% for dog in dog_list %}
            {{ }}
    {% endfor %}
{% endblock %}

Notice that block, for, if and else, as well as 'with' are all automatically closed. Using endfor, endif or endblock will throw an exception.



Surrounds the filtered text with