### Navigation

- index
- modules |
- next |
- previous |
- django-treebeard 2.0b1 documentation »

# Introduction

Everything you need to get working quickly.

## Prerequisites

`django-treebeard` needs at least Python 2.5 to run, and Django 1.4 or better.

## Installation

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

### setup.py

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

    python setup.py install

### .deb packages

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

    apt-get install python-django-treebeard

or:

    aptitude install python-django-treebeard

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

## Configuration

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

Note

If you are going to use the `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' % self.name

Run syncdb:

    python manage.py 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(root.id).add_child(name='Memory')
    >>> get(node.id).add_sibling(name='Hard Drives')
    <Category: Category: Hard Drives>
    >>> get(node.id).add_sibling(name='SSD')
    <Category: Category: SSD>
    >>> get(node.id).add_child(name='Desktop Memory')
    <Category: Category: Desktop Memory>
    >>> get(node.id).add_child(name='Laptop Memory')
    <Category: Category: Laptop Memory>
    >>> get(node.id).add_child(name='Server Memory')
    <Category: Category: Server Memory>

Note

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 `treebeard.models.Node` API reference for detailed info.

### Navigation

- index
- modules |
- next |
- previous |
- django-treebeard 2.0b1 documentation »