Introduction

Why type:

<div class="left" id="banner">
    Greetings!
</div>

when you can just type:

.left#banner
    Greetings!

... and do something more fun with all the time you save not typing angle brackets and remembering to close tags?

The syntax above is Haml - a templating language used extensively in the Ruby on Rails community. This library lets Django developers use a Haml like syntax in their templates. It's not a template engine in itself, but simply a compiler which will convert "HamlPy" files into templates that Django can understand.

This project is a fork of the no longer maintained HamlPy. It introduces Python 3 support, support for new Django versions, and a host of new features and bug fixes. Note that the package name is now django-hamlpy.

Installing

The latest stable version can be installed using pip:

pip install django-hamlpy

And the latest development version can be installed directly from GitHub:

pip install git+https://github.com/nyaruka/django-hamlpy

NOTE: If you run into build errors, then you may need to install python's development package.

Syntax

Almost all of the syntax of Haml is preserved.

#profile(style="width: 200px")
    .left.column
        #date 2010/02/18
        #address Toronto, ON
    .right.column<
        #bio Jesse Miller

turns into:

<div id='profile' style="width: 200px">
    <div class='left column'>
        <div id='date'>2010/02/18</div>
        <div id='address'>Toronto, ON</div>
    </div>
    <div class='right column'><div id='bio'>Jesse Miller</div></div>
</div>

The main difference is instead of interpreting Ruby, or even Python we instead can create Django tags and variables. For example:

%ul#athletes
    - for athlete in athlete_list
        %li.athlete{'id': 'athlete_#{ athlete.pk }'}= athlete.name

becomes...

<ul id='athletes'>
    {% for athlete in athlete_list %}
        <li class='athlete' id='athlete_{{ athlete.pk }}'>{{ athlete.name }}</li>
    {% endfor %}
</ul>

Usage

There are two different ways to use this library.

Option 1: Template loaders

These are Django template loaders which will convert any templates with .haml or .hamlpy extensions to regular Django templates whenever they are requested by a Django view. To use them, add them to the list of template loaders in your Django settings, e.g.

TEMPLATES=[
    {
        'BACKEND': 'django.template.backends.django.DjangoTemplates',
        'DIRS': ['./templates'],
        'OPTIONS': {
            'loaders': (
                'hamlpy.template.loaders.HamlPyFilesystemLoader',
                'hamlpy.template.loaders.HamlPyAppDirectoriesLoader',
                ...
            ), 
        }
    }
]

Ensure they are listed before the standard Django template loaders or these loaders will try to process your Haml templates.

Template caching

You can use these loaders with template caching - just add django.template.loaders.cached.Loader to your list of loaders, e.g.

'loaders': (
    ('django.template.loaders.cached.Loader', (
        'hamlpy.template.loaders.HamlPyFilesystemLoader',
        'hamlpy.template.loaders.HamlPyAppDirectoriesLoader',
        ...
    )),
)

Settings

You can configure the Haml compiler with the following Django settings:

HAMLPY_ATTR_WRAPPER -- The character that should wrap element attributes. Defaults to ' (an apostrophe).
HAMLPY_DJANGO_INLINE_STYLE -- Whether to support ={...} syntax for inline variables in addition to #{...}. Defaults to False.

Option 2: Watcher

The library can also be used as a stand-alone program. There is a watcher script which will monitor Haml files in a given directory and convert them to HTML as they are edited.

usage: hamlpy_watcher.py [-h] [-v] [-i EXT [EXT ...]] [-ext EXT] [-r S]
                         [--tag TAG] [--attr-wrapper {",'}] [--django-inline]
                         [--jinja] [--once]
                         input_dir [output_dir]

positional arguments:
  input_dir             Folder to watch
  output_dir            Destination folder

optional arguments:
  -h, --help            show this help message and exit
  -v, --verbose         Display verbose output
  -i EXT [EXT ...], --input-extension EXT [EXT ...]
                        The file extensions to look for.
  -ext EXT, --extension EXT
                        The output file extension. Default is .html
  -r S, --refresh S     Refresh interval for files. Default is 3 seconds.
                        Ignored if the --once flag is set.
  --tag TAG             Add self closing tag. eg. --tag macro:endmacro
  --attr-wrapper {",'}  The character that should wrap element attributes.
                        This defaults to ' (an apostrophe).
  --django-inline       Whether to support ={...} syntax for inline variables
                        in addition to #{...}
  --jinja               Makes the necessary changes to be used with Jinja2.
  --once                Runs the compiler once and exits on completion.
                        Returns a non-zero exit code if there were any compile
                        errors.

Create message files for translation

HamlPy must first be included in Django's list of apps, i.e.

INSTALLED_APPS = [
  ...
  'hamlpy'
  ...
]

Then just include your Haml templates along with all the other files which contain translatable strings, e.g.

python manage.py makemessages --extension haml,html,py,txt

Reference

Check out the reference file for the complete syntax reference and more examples.

Class Based Views

This library also provides the same class based generic views than django with the enhancement that they start by looking for templates endings with *.haml and *.hamlpy in addition to their default templates. Apart from that, they are exactly the same class based generic views. For example:

from hamlpy.views.generic import DetailView, ListView
from my_app.models import SomeModel

# will look for the templates `my_app/somemodel_detail.haml`,
# `my_app/somemodel_detail.hamlpy` and  `my_app/somemodel_detail.html`
DetailView.as_view(model=SomeModel)

# will look for the templates `my_app/somemodel_list.haml`,
# `my_app/somemodel_list.hamlpy` and  `my_app/somemodel_list.html`
ListView.as_view(model=SomeModel)

The available view classes are:

Display views:

Edit views:

Date related views:

All views are importable from hamlpy.views.generic and are built using the HamlExtensionTemplateView mixin which you can use to create your own custom Haml-using views. For example:

from hamlpy.views.generic import HamlExtensionTemplateView

class MyNewView(HamlExtensionTemplateView, ParentViewType):
    pass

Note: HamlExtensionTemplateView needs to be first in the inheritance list.

Contributing

We're always happy to have contributions to this project. To get started you'll need to clone the project and install the dependencies:

poetry install

Please write tests for any new features and always ensure the current tests pass. To run the tests, use:

py.test hamlpy

To run the performance test, use:

python -m hamlpy.test.test_templates

nyaruka / django-hamlpy