django-treebeard / docs / intro.rst

Full commit


Everything you need to get working quickly.


django-treebeard needs at least Python 2.4 to run, and Django 1.0 or better.


You have several ways to install django-treebeard. If you're not sure, just use pip

pip (or easy_install)

You can install the release versions from django-treebeard's PyPI page using pip:

pip install django-treebeard

or if for some reason you can't use pip, you can try easy_install, (at your own risk):

easy_install --always-unzip django-treebeard

Download a release from the treebeard download page and unpack it, then run:

python install

.deb packages

Both Debian and Ubuntu include django-treebeard as a package, so you can just use:

apt-get install python-django-treebeard


aptitude install python-django-treebeard

Remember that the packages included in linux distributions are usually not the most recent versions.


Add 'treebeard' to the INSTALLED_APPS section in your django settings file.


If you are going to use the :class:`Treeadmin <treebeard.admin.TreeAdmin>` class, you need to add the path to treebeard's templates in TEMPLATE_DIRS. Also you need to enable django-core-context-processors-request in the TEMPLATE_CONTEXT_PROCESSORS setting in your django settings file.

Basic Usage

Create a basic model for your tree. In this example we'll use a Materialized Path tree:

from django.db import models
from treebeard.mp_tree import MP_Node

class Category(MP_Node):
    name = models.CharField(max_length=30)

    node_order_by = ['name']

    def __unicode__(self):
        return 'Category: %s' %

Run syncdb:

python syncdb

Let's create some nodes:

>>> get = lambda node_id: Category.objects.get(pk=node_id)
>>> root = Category.add_root(name='Computer Hardware')
>>> node = get('Memory')
>>> get('Hard Drives')
<Category: Category: Hard Drives>
>>> get('SSD')
<Category: Category: SSD>
>>> get('Desktop Memory')
<Category: Category: Desktop Memory>
>>> get('Laptop Memory')
<Category: Category: Laptop Memory>
>>> get('Server Memory')
<Category: Category: Server Memory>


Why retrieving every node again after the first operation? Because django-treebeard uses raw queries for most write operations, and raw queries don't update the django objects of the db entries they modify.

We just created this tree:

You can see the tree structure with code::
>>> Category.dump_bulk()
[{'id': 1, 'data': {'name': u'Computer Hardware'},
  'children': [
     {'id': 3, 'data': {'name': u'Hard Drives'}},
     {'id': 2, 'data': {'name': u'Memory'},
      'children': [
         {'id': 5, 'data': {'name': u'Desktop Memory'}},
         {'id': 6, 'data': {'name': u'Laptop Memory'}},
         {'id': 7, 'data': {'name': u'Server Memory'}}]},
     {'id': 4, 'data': {'name': u'SSD'}}]}]
>>> Category.get_annotated_list()
[(<Category: Category: Computer Hardware>,
  {'close': [], 'level': 0, 'open': True}),
 (<Category: Category: Hard Drives>,
  {'close': [], 'level': 1, 'open': True}),
 (<Category: Category: Memory>,
  {'close': [], 'level': 1, 'open': False}),
 (<Category: Category: Desktop Memory>,
  {'close': [], 'level': 2, 'open': True}),
 (<Category: Category: Laptop Memory>,
  {'close': [], 'level': 2, 'open': False}),
 (<Category: Category: Server Memory>,
  {'close': [0], 'level': 2, 'open': False}),
 (<Category: Category: SSD>,
  {'close': [0, 1], 'level': 1, 'open': False})]

Read the :class:`treebeard.models.Node` API reference for detailed info.