django-treemenus 0.9.2

Installing an official release

django-treemenus is available on PyPI, and can be installed using Pip:

pip install django-treemenus

Alternatively, official source releases are made available at https://pypi-hypernode.com/pypi/django-treemenus

Download the .zip distribution file and unpack it. Inside is a script named setup.py. Run this command:

python setup.py install

…and the package will install automatically.

Installing the development version

If you prefer to update Django Tree Menus occasionally to get the latest bug fixes and improvements before they are included in an official release, do a git clone instead:

git clone https://github.com/jphalip/django-treemenus

Then add the treemenus folder to your PYTHONPATH or symlink (junction, if you’re on Windows), such as in your Python’s site-packages directory.

Hooking Tree Menus to your project

1. Add treemenus to the INSTALLED_APPS setting of your Django project.

2. Create django-treemenus tables by running the following command from the root of your project:

   python manage.py syncdb

3. Create and add your custom templates to your project template folder. These templates are necessary to specify how you want your menus to be displayed on your site (See further below for more details on the use of templates). Some sample templates are also provided in the package to get you started.

treemenus/menu.html

Template to specify how to display a menu.

Context:

• menu

  Pointer to the menu to display. You can access its root item with menu.root_item.

• menu_type (optional)

  This variable will only be present if it has been specified when calling the show_menu template tag. (See the “Template tags” section for more details).

Example for this template:

{% load tree_menu_tags %}

{% ifequal menu_type "unordered-list" %}
    <ul>
        {% for menu_item in menu.root_item.children %}
            {% show_menu_item menu_item %}
        {% endfor %}
    </ul>
{% endifequal %}
{% ifequal menu_type "ordered-list" %}
    <ol>
        {% for menu_item in menu.root_item.children %}
            {% show_menu_item menu_item %}
        {% endfor %}
    </ol>
{% endifequal %}

treemenus/menu_item.html

Template to specify how to display a menu item.

Context:

• menu_item

  Pointer to the menu_item to display. You can directly access all its methods and variables.

• menu_type (optional)

  This variable will only be accessible if it has been specified when calling the show_menu template tag (See the “Template tags” section for more details).

Example for this template:

{% load tree_menu_tags %}
<li><a href="{{ menu_item.url }}">{{ menu_item.caption }}</a>
    {% if menu_item.children %}
    <ul>
        {% for child_item in menu_item.children %}
        {% show_menu_item child_item %}
        {% endfor %}
    </ul>
    {% endif %}
</li>

show_menu

This is the starting point. Call it wherever you want to display your menu (most of the time it will be in your site’s base template).

There are two attributes:

• menu_name

  Name of the menu to display, as it has been saved via the admin interface.

• menu_type

  This attribute is optional. If it is given it is simply passed to the treemenus/menu.html template. It does not have any particular pre-defined function but can be tested with (% ifequal menu_type “sometype” %} to determine how to display the menu (See above example for the template treemenus/menu.html).

Example of use:

{% show_menu "TopMenu" %}
...
{% show_menu "LeftMenu" "vertical" %}
...
{% show_menu "RightMenu" "horizontal" %}

show_menu_item

This tag allows you to display a menu item, which is the only attribute.

Example of use:

{% show_menu_item menu_item %}

reverse_named_url

This tag allows you to reverse the named URL of a menu item, which is passed as a single string. To know more about named URLs, refer to the Django template documentation. For example, the passed value could be ‘latest_news’ or ‘show_profile user.id’, and that would be reversed to the corresponding URL (as defined in your URLConf).

Example of use:

<li><a href="{% reverse_named_url menu_item.named_url %}">{{ menu_item.caption }}</a></li>

Menu

There is only one attribute that is available: root_item, which points to… you got it, the menu’s root item.

Menu item

• menu

  Returns the menu to which it belongs.

• url

  Returns the item’s url.

  Example of use:

  <li><a href="{{ menu_item.url }}">{{ menu_item.caption }}</a></li>

• parent

  Returns the menu item’s parent (that is, another menu item).

• rank

  Returns the item’s rank amongst its siblings. The first item of a branch has a rank of 0, the second one has a rank of 1, etc. To change an item’s ranking you can move it up or down through the admin interface.

  Example of use:

  <li><a class="menuitem-{{ menu_item.rank }}" href="{{ menu_item.url }}">{{ menu_item.caption }}</a></li>

• level

  Returns the item’s level in the hierarchy. This is automatically calculated by the system. For example, the root item has a level 0, and its children have a level 1.

  Example of use:

  {% ifequal menu_item.level 1 %}
      <li><a class="top-item" href="{{ menu_item.url }}">{{ menu_item.caption }}</a></li>
  {% else %}
      <li><a href="{{ menu_item.url }}">{{ menu_item.caption }}</a></li>
  {% endifequal %}

• caption

  Returns the item’s caption.

• named_url

  Use this attribute if you want to use named URLs instead of raw URLs.

  Example of use:

  <li><a href="{% reverse_named_url menu_item.named_url %}">{{ menu_item.caption }}</a></li>

• has_children

  Returns True if the item has some children, False otherwise.

• children

  Returns a list with the menu item’s children, ordered by rank.

  Example of use:

  {% if menu_item.has_children %}
      <li><a class="daddy" href="{{ menu_item.url }}">{{ menu_item.caption }}</a>
          <ul>
              {% for child in menu_item.children %}
                  {% show_menu_item child %}
              {% endfor %}
          </ul>
      </li>
  {% else %}
      <li><a href="{{ menu_item.url }}">{{ menu_item.caption }}</a></li>
  {% endif %}

• siblings

  Returns a list with the menu item’s siblings (i.e all other items that have the same parent), ordered by rank.

Internationalization

Making your menus multi-lingual is very easy if you use the Django internationalization module. What you can do is apply the translation to the caption attribute of a menu_item. For example:

{% load i18n %}
...
<li><a href="{{ menu_item.url }}">{% trans menu_item.caption %}</a></li>

Then, add manually the translation entries in your *.po file.

If you use more complex or custom translation systems, you may simply define your extension class (or create it if you don’t already have one) with a method to manage the translation, for example:

class MenuItemExtension(models.Model):
    menu_item = models.OneToOneField (MenuItem, related_name="extension")
    ...

    def translation():
        translation = do_something_with(self.menu_item.caption)
        return translation

And then in your template:

<li><a href="{{ menu_item.url }}">{% trans menu_item.extension.translation %}</a></li>

Login restriction

If you want to make some of your menus items private and only available to logged in users, that’s simple! Simply define your extension class (or create it if you don’t already have one) like the following:

class MenuItemExtension(models.Model):
    menu_item = models.OneToOneField (MenuItem, related_name="extension")
    protected = models.BooleanField(default=False)
    ...

And then in your template:

{% if menu_item.extension.protected %}
    {% if user.is_authenticated %}
        <li><a href="{{ menu_item.url }}">{{ menu_item.caption }}</a></li>
    {% endif %}
{% else %}
    <li><a href="{{ menu_item.url }}">{{ menu_item.caption }}</a></li>
{% endif %}

(assuming that the context variable ‘user’ represents the currently logged-in user)

Automatically select menu items

Here I’m going to explain how to automatically select a menu item when visiting a given page of your site. This is a good example to illustrate the power of extensions for customizing your menu’s behaviour. For this example, let’s say that you’d like to visually select the menu item ‘Contact’ when visiting the url ‘http://www.example.com/contact/’

First, define your extension class (or create it if you don’t already have one) like the following:

class MenuItemExtension(models.Model):
    menu_item = models.OneToOneField (MenuItem, related_name="extension")
    selected_patterns = models.TextField(blank=True)

selected_patterns is the attribute which will specify for what urls the menu item should have the ‘selected’ status. Refer to the section on extensions above to see how to hook your extension class to your menus.

Now, in the admin section, edit the ‘Contact’ menu item and type the following line in its selected_patterns textfield:

^/contact/$

Here we’re using regular expressions so that gives us some flexibility to specify our ‘selected’ url patterns. Refer to the official python documentation on regular expressions syntax for more detailed information. In this example we’re only using one regular expression pattern (^/contact/$) but you could add as many as you’d like by typing a different pattern on each line of the textfield.

Then, in your menu_item.html template, use the following ‘if’ statement:

{% load menu_extension_filters %}
...
<li><a href="{{ menu_item.url }}" class="{% if menu_item.extension.selected_patterns|match_path:request.path %}selected{% endif %}">{{ menu_item.caption }}</a></li>

With this code, every menu item whose attribute selected_patterns matches the current url will be given the ‘selected’ CSS class (it’s up to you to define in your style sheet what that ‘selected’ class actually does - maybe change the colour or the font?). In this example we’re allocating a special style to visually distinguish the selected menu items, but you’re obviously free to use the ‘if’ statement above to do any form of disctinction you like (for example displaying all children of a selected menu, etc.) Don’t forget to load the menu_extension_filters module, which we’re going to create in a moment.

We now need to create the ‘match_path’ filter. In your menu_extension application (or whatever name you’ve given to your menu extension application) create a directory templatetags containing two files: __init__.py (leave it empty) and menu_extension_filters.py containing the following code:

import re
from django import template

register = template.Library()

def match_path(patterns, path):
    if patterns:
        for pattern in patterns.splitlines():
            if re.compile(pattern).match(path):
                return True
    return False
register.filter('match_path', match_path)

What it does is test each pattern on each line of our patterns (remember, you can add one pattern on each line of the selected_patterns textfield) and returns true if any of those matches the given path.

Finally, to be able to access the current url through request.path in your template, you need to do 2 things:

1) Add django.core.context_processors.request to your TEMPLATE_CONTEXT_PROCESSORS setting (see the Django documentation on context processors for more details).

2) Use a RequestContext object in your views to pass to your templates. (see Django documentation on RequestContext).