===========
Django Yama
===========

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

Django Yama (Yet Another Menuing App) is a fairly generic menuing
application for Django 1.1 (and up). It supports hierarchical
(tree-structure) menus of arbitrary depth, and enables you to create
menus linking to model objects and views from other Django apps, as
well as external URLs.

The admin part of the app is completely customized, utilizing jQuery
to provide a simple user interface. The interface was mostly ripped
off from^W ^W ^W influenced by `django-page-cms
<http://code.google.com/p/django-page-cms/>`_.

Currently there is no front-end functionality included as it would be
difficult to find a common denominator. However, the best way of
deploying django-yama would probably be by the means of a custom
template context processor.  

Installation and configuration
==============================

The package is now available through PyPI.  It depends on the
`django-mptt <http://code.google.com/p/django-mptt/>`_ for its
hierarchical structure, and obviously on Django itself, so you will
also need to install those.

Alternatively, you can check out the latest revision from the Mercurial
repository: ::

  hg clone http://django-yama.googlecode.com/hg django-yama

Having installed Yama, you need a couple of usual steps:

* Add ``'yama'`` to your ``INSTALLED_APPS``

* To create the necessary database tables, run ``python manage.py
  syncdb``; alternatively, if you're using South, run ``python
  manage.py migrate yama``.

And a few more unusual ones:

* Since Yama uses Django's machinery for Javascript translation,
  you need to provide an entry for Django's ``javascript_catalog``
  view in your ``urls.py``. Typically, that would look something
  like: ::

      (r'^jsi18n/(?P<packages>\S+?)/$', 'django.views.i18n.javascript_catalog'),

* If you don't intend to link to objects or views (i.e. plan to enter
  the URLs directly), you're good to go.  Otherwise, you need to tell
  Yama which models and views you wish to link to. You can either edit
  ``settings.py`` in the yama directory, or edit your site-wide
  ``settings.py`` and adjust the following couple of settings:

  * ``YAMA_MODELS``, which is a dictionary. Keys are pairs in the form
    ``('app_label', 'model name'), and values are ``Q`` objects which
    determine the subset of model instances which can be used as menu
    targets. Alternatively, values can also be callables which return
    ``Q`` objects; these callables are given a single argument, a
    ``HttpRequest`` object. In fact, callables are your only option in
    site-wide ``settings.py``, since importing ``Q`` objects at the
    top level would cause a circular import. Here's an example: ::

      def user_list(request):
          from django.db.models import Q
          return Q(is_active=True)
       
      YAMA_MODELS = {('auth', 'User') : user_list}

    All the given models are expected to implement the
    ``get_absolute_url`` method.

  * ``YAMA_VIEWS``, which is a sequence of pairs. Each pair takes the
    form of ``('reverse-able name', 'display name')``. Example: ::

      YAMA_VIEWS = (
           ('blog-index', _('Blog index')),
           ('blog.views.archive', _('Blog archive')),
      )
 
    Currently, the views are expected not to take any arguments (apart
    from ``request``).
