django-sitetree documentation¶

Upgrade hint¶

When switching from older version of SiteTree to newer do not forget to upgrade your database schema.

That could be done with the following command issued in your Django project directory:

./manage.py migrate

Note that the command requires South.

Making tree¶

Taken from StackOverflow.

In this tutoral we create sitetree that could handle URI like /categoryname/entryname.

To create a tree:

1. Go to site administration panel;

2. Click +Add near ‘Site Trees’;

3. Enter alias for your sitetree, e.g. ‘maintree’. You’ll address your tree by this alias in template tags;

4. Push ‘Add Site Tree Item’;

5. Create first item:

   Parent - As it is root item that would have no parent.
   Title - Let it be 'My site'.
   URL - This URL is static, so put here '/'.
   

6. Create second item (that one would handle ‘categoryname’ from your ‘categoryname/entryname’):

   Parent - Choose 'My site' item from step 5.
   Title - Put here 'Category #{{ category.id }}'.
   URL - Put named URL 'category-detailed category.name'.
   
   In 'Additional settings': check 'URL as Pattern' checkbox.
   

7. Create third item (that one would handle ‘entryname’ from your ‘categoryname/entryname’):

   Parent - Choose 'Category #{{ category.id }}' item from step 6.
   Title - Put here 'Entry #{{ entry.id }}'.
   URL - Put named URL 'entry-detailed category.name entry.name'.
   
   In 'Additional settings': check 'URL as Pattern' checkbox.
   

8. Put ‘{% load sitetree %}’ into yor template to have access to sitetree tags.

9. Put ‘{% sitetree_menu from “maintree” %}’ into your template to render menu.

10. Put ‘{% sitetree_breadcrumbs from “maintree” %}’ into your template to render breadcrumbs.

Steps 6 and 7 clarifications:

• In titles we use Django template variables, which would be resolved just like they do in your templates.

  E.g.: You made your view for ‘categoryname’ (let’s call it ‘detailed_category’) to pass category object into template as ‘category’ variable. Suppose that category object has ‘id’ property. In your template you use ‘{{ category.id }}’ to render id. And we do just the same for site tree item in step 6.

• In URLs we use Django’s named URL patterns (documentation). That is almost idential to usage of Django ‘url‘ tag in templates.

  Your urls configuration for steps 6, 7 supposed to include:

  url(r'^(?P<category_name>\S+)/(?P<entry_name>\S+)/$', 'detailed_entry', name='entry-detailed'),
  url(r'^(?P<category_name>\S+)/$', 'detailed_category', name='category-detailed'),
  

  Consider ‘name’ argument values of ‘url’ function.

  So, putting ‘entry-detailed category.name entry.name’ in step 7 into URL field we tell sitetree to associate that sitetree item with URL named ‘entry-detailed’, passing to it category_name and entry_name parameters.

sitetree_menu¶

This tag renders menu based on sitetree.

Usage example:

{% sitetree_menu from "mytree" include "trunk,topmenu" %}

This command renders as a menu sitetree items from tree named ‘mytree’, including items under ‘trunk’ and ‘topmenu’ aliased items. That means that ‘trunk’ and ‘topmenu’ themselves won’t appear in a menu, but rather their ancestors. If you need item filtering behaviour please use tree hooks.

Aliases are given to items through Django’s admin site.

Note that there are some reserved aliases. To illustrate how do they work, take a look at the sample tree:

Users
  |-- Moderators
  |-- Ordinary

Articles
  |-- About cats
        |-- Good
        |-- Bad
        |-- Ugly
  |-- About dogs
  |-- About mice

Contacts
  |-- Russia
        |-- Web
              |-- Public
              |-- Private
        |-- Postal
  |-- Australia
  |-- China

• trunk - get items without parents (root items);

  Renders:

  Users
  Articles
  Contacts
  

• this-children - get items under item resolved as current for the current page;

  Considering that we are now at Articles renders:

  About cats
  About dogs
  About mice
  

• this-siblings - get items under parent of item resolved as current for the current page (current item included);

  Considering that we are now at Bad renders:

  Good
  Bad
  Ugly
  

• this-ancestor-children - items under grandparent item (closest to root) for the item resolved as current for the current page.

  Considering that we are now at Public renders:

  Web
  Postal
  

Thus in the template tag example above ‘trunk’ is reserved alias, and ‘topmenu’ alias is given to an item through admin site.

Sitetree items could be addressed not only by aliases but also by IDs:

{% sitetree_menu from "mytree" include "10" %}

sitetree_breadcrumbs¶

This tag renders breadcrumbs path (from tree root to current page) based on sitetree.

Usage example:

{% sitetree_breadcrumbs from "mytree" %}

This command renders breadcrumbs from tree named ‘mytree’.

sitetree_tree¶

This tag renders entire site tree.

Usage example:

{% sitetree_tree from "mytree" %}

This command renders sitetree from tree named ‘mytree’.

sitetree_page_title¶

This tag renders current page title resolved against definite sitetree. Title is taken from sitetree item title resolved for current page.

Usage example:

{% sitetree_page_title from "mytree" %}

This command renders current page title from tree named ‘mytree’.

sitetreedump¶

Sends sitetrees from database as a fixture in JSON format to output.

Output all trees and items into treedump.json file example:

python manage.py sitetreedump > treedump.json

You can export only trees that you need by supplying their aliases separated with spaces:

python manage.py sitetreedump my_tree my_another_tree > treedump.json

If you need to export only tree items without trees use --items_only command switch:

python manage.py sitetreedump --items_only my_tree > items_only_dump.json

Use --help command switch to get quick help on the command:

python manage.py sitetreedump --help

sitetreeload¶

This command loads sitetrees from a fixture in JSON format into database.

Command makes use of --mode command switch to control import strategy.

a) append (default) mode should be used when you need to extend sitetree data that is now in DB with that from a fixture.

Note: In this mode trees and tree items identifiers from a fixture will be changed to fit existing tree structure.

b) replace mode should be used when you need to remove all sitetree data existing in DB and replace it with that from a fixture.

Warning: Replacement is irreversible. You should probably dump sitetree data if you think that you might need it someday.

Using replace mode:

python manage.py sitetreeload --mode=replace treedump.json

Import all trees and items from treedump.json file example:

python manage.py sitetreeload treedump.json

Use --items_into_tree command switch and alias of target tree to import all tree items from a fixture there. This will not respect any trees information from fixture file - only tree items will be considered. Keep in mind also that this switch will automatically change sitetreeload commmand into append mode:

python manage.py sitetreeload --items_into_tree=my_tree items_only_dump.json

Use --help command switch to get quick help on the command:

python manage.py sitetreeload --help

Styling built-in templates¶

Use CSS to style default templates for your needs. Templates are deliberately made simple, and only consist of ul, li and a tags.

Nevertheless pay attention that menu template also uses two CSS classes marking tree items:

• current_item — marks item in the tree, corresponding to current page;
• current_branch — marks all ancestors of current item, and current item itself.

Overriding built-in templates¶

To customize visual representation of navigation elements you should override the built-in SiteTree templates as follows:

1. Switch to sitetree folder
2. Switch further to ‘templates/sitetree’
3. There you’ll find the following templates:

• breadcrumbs.html
• menu.html
• tree.html

4. Copy whichever of them you need into your project templates directory and feel free to customize it.
5. See Advanced SiteTree tags section for clarification on two advanced SiteTree template tags.

Templates for Foundation CSS Framework¶

Information about Foundation CSS Framework is available at http://foundation.zurb.com

The following templates are bundled with SiteTree:

• sitetree/menu_foundation.html

  This template can be used to construct Foundation Nav Bar (classic horizontal top menu) from a sitetree.

  Note

  The template renders no more than two levels of a tree with hover dropdowns for root items having children.

• sitetree/menu_foundation-vertical.html

  This template can be used to construct a vertical version of Foundation Nav Bar, suitable for sidebar navigation.

  Note

  The template renders no more than two levels of a tree with hover dropdowns for root items having children.

• sitetree/sitetree/menu_foundation_sidenav.html

  This template can be used to construct a Foundation Side Nav.

  Note

  The template renders only one tree level.

You can take a look at Foundation navigation elements examples at http://foundation.zurb.com/docs/navigation.php

Templates for Bootstrap CSS Framework¶

Information about Bootstrap CSS Framework is available at http://twitter.github.com/bootstrap/

The following templates are bundled with SiteTree:

• sitetree/breadcrumbs_bootstrap.html

  This template can be used to construct a breadcrumb navigation from a sitetree.

• sitetree/menu_bootstrap.html

  This template can be used to construct menu contents for Boostrap Navbar.

  Warning

  To widen the number of possible use-cases for which this template can be applied, it renders only menu contents, but not Navbar container itself.

  This means that one should wrap sitetree_menu call into the appropriately styled divs (i.e. having classes navbar, navbar-inner, etc.).

  Please see Boostrap Navbar documentation for more information on subject.

  Note

  The template renders no more than two levels of a tree with hover dropdowns for root items having children.

• sitetree/menu_bootstrap_navlist.html

  This template can be used to construct a Boostrap Nav list.

  Note

  The template renders only one tree level.

You can find Bootstrap navigation elements examples at http://twitter.github.com/bootstrap/components.html#navbar

sitetree_children¶

Implements down the tree traversal with rendering.

Usage example:

{% sitetree_children of someitem for menu template "sitetree/mychildren.html" %}

Used to render child items of specific sitetree item ‘someitem’ for ‘menu’ navigation type, using template “sitetree/mychildren.html”.

Allowed navigation types: 1) menu; 2) sitetree.

Basically template argument should contain path to current template itself.

sitetree_url¶

Resolves site tree item’s url or url pattern.

Usage example:

{% sitetree_url for someitem params %}

This tag is much the same as Django built-in ‘url’ tag. The difference is that after ‘for’ it should get site tree item object.

And, yes, you can pass some params after that object.

Inlines override example¶

In the example below we’ll use django-seo application from https://github.com/willhardy/django-seo

According to django-seo documentation it allows an addition of custom metadata fields to your models, so we use it to connect metadata to sitetree items.

That’s how one might render django-seo inline form on sitetree item create and edit pages:

from rollyourown.seo.admin import get_inline
from sitetree.admin import TreeItemAdmin, TreeAdmin, override_tree_admin, override_item_admin
# Let's suppose our application contains seo.py with django-seo metadata class defined.
from myapp.seo import CustomMeta


class CustomTreeItemAdmin(TreeItemAdmin):
    inlines = [get_inline(CustomMeta)]

override_item_admin(CustomTreeItemAdmin)