Metadata-Version: 2.0
Name: django-hamlpy
Version: 1.1
Summary: Haml like syntax for Django templates.
Home-page: http://github.com/nyaruka/django-hamlpy
Author: Nyaruka
Author-email: code@nyaruka.com
License: MIT
Keywords: haml django converter
Platform: UNKNOWN
Classifier: Environment :: Web Environment
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python
Classifier: Framework :: Django
Requires-Dist: django
Requires-Dist: future
Requires-Dist: regex
Requires-Dist: six

Introduction
============

|Build Status| |Coverage Status| |PyPI Release|

Why type:

.. code:: html

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

when you can just type:

.. code:: haml

    .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 <http://www.haml-lang.com>`__ - 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 <https://github.com/jessemiller/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 <http://pypi.python.org/pypi/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 <http://stackoverflow.com/a/21530768/2896976>`__.

Syntax
------

Almost all of the syntax of Haml is preserved.

.. code:: haml

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

turns into:

.. code:: htmldjango

    <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:

.. code:: haml

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

becomes...

.. code:: htmldjango

    <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.

.. code:: python

    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.

.. code:: python

    '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.

.. code:: python

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

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

.. code:: bash

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

Reference
---------

Check out the
`reference <http://github.com/nyaruka/django-hamlpy/blob/master/REFERENCE.md>`__
file for the complete syntax reference and more examples.

Class Based Views
-----------------

This library also provides `the same class based generic views than
django <https://docs.djangoproject.com/en/1.10/topics/class-based-views/generic-display/>`__
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:

.. code:: python

    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:

-  `DetailView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#detailview>`__
-  `ListView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#listview>`__

Edit views:

-  `CreateView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#createview>`__
-  `UpdateView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#updateview>`__
-  `DeleteView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#deleteview>`__

Date related views:

-  `DateDetailView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#datedetailview>`__
-  `ArchiveIndexView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#archiveindexview>`__
-  `YearArchiveView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#yeararchiveview>`__
-  `MonthArchiveView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#montharchiveview>`__
-  `WeekArchiveView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#weekarchiveview>`__
-  `DayArchiveView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#dayarchiveview>`__
-  `TodayArchiveView <https://docs.djangoproject.com/en/1.10/ref/class-based-views/generic-display/#todayarchiveview>`__

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:

.. code:: python

    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:

::

    virtualenv env
    source env/bin/activate
    pip install -r requirements/base.txt
    pip install -r requirements/tests.txt

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

.. |Build Status| image:: https://travis-ci.org/nyaruka/django-hamlpy.svg?branch=master
   :target: https://travis-ci.org/nyaruka/django-hamlpy
.. |Coverage Status| image:: https://coveralls.io/repos/github/nyaruka/django-hamlpy/badge.svg?branch=master
   :target: https://coveralls.io/github/nyaruka/django-hamlpy?branch=master
.. |PyPI Release| image:: https://img.shields.io/pypi/v/django-hamlpy.svg
   :target: https://pypi.python.org/pypi/django-hamlpy/


