Shipping sitetrees with your apps

SiteTree allows you to define sitetrees within your apps.

Defining a sitetree

Let’s suppose you have books application and want do define a sitetree for it.

• First create sitetrees.py in the directory of books app.

• Then define a sitetree with the help of tree and item functions from sitetree.utils module and assign it to sitetrees module attribute

from sitetree.utils import tree, item

# Be sure you defined `sitetrees` in your module.
sitetrees = (
  # Define a tree with `tree` function.
  tree('books', items=[
      # Then define items and their children with `item` function.
      item('Books', 'books-listing', children=[
          item('Book named "{{ book.title }}"', 'books-details', in_menu=False, in_sitetree=False),
          item('Add a book', 'books-add', access_by_perms=['booksapp.allow_add']),
          item('Edit "{{ book.title }}"', 'books-edit', in_menu=False, in_sitetree=False)
      ])
  ]),
  # ... You can define more than one tree for your app.
)

Please see tree and item signatures for possible options.

Note

If you added extra fields to the Tree and TreeItem models, then you can specify their values when instantiating item see Sitetree definition with custom models

Export sitetree to DB

Now when your app has a defined sitetree you can use sitetree_resync_apps management command to instantly move sitetrees from every (or certain) applications into DB:

python manage.py sitetree_resync_apps

Or solely for books application:

python manage.py sitetree_resync_apps books

Dynamic sitetree structuring

Optionally you can structure app-defined sitetrees into existing or new trees runtime.

Basically one should compose a dynamic tree with compose_dynamic_tree() and register it with register_dynamic_trees().

Let’s suppose the following code somewhere where app registry is already created, e.g. config.ready() or even in urls.py of your project.

from sitetree.sitetreeapp import register_dynamic_trees, compose_dynamic_tree
from sitetree.utils import tree, item


register_dynamic_trees(

    # Gather all the trees from `books`,
    compose_dynamic_tree('books'),

    # or gather all the trees from `books` and attach them to `main` tree root,
    compose_dynamic_tree('books', target_tree_alias='main'),

    # or gather all the trees from `books` and attach them to `for_books` aliased item in `main` tree,
    compose_dynamic_tree('books', target_tree_alias='main', parent_tree_item_alias='for_books'),

    # or even define a tree right at the process of registration.
    compose_dynamic_tree((
        tree('dynamic', items=(
            item('dynamic_1', 'dynamic_1_url', children=(
                item('dynamic_1_sub_1', 'dynamic_1_sub_1_url'),
            )),
            item('dynamic_2', 'dynamic_2_url'),
        )),
    )),

    # Line below tells sitetree to drop and recreate cache, so that all newly registered
    # dynamic trees are rendered immediately.
    reset_cache=True
)

Note

If you use only dynamic trees you can set SITETREE_DYNAMIC_ONLY = True to prevent the application from querying trees and items stored in DB.