Skip to content

Custom Forms and Fields

Occasionally you may want to link some site entities (e.g. Polls, Articles) to certain sitetree items (as to categorize them). You can achieve it with the help of generic forms and fields shipped with SiteTree.

TreeItemForm

You can inherit from that form to have a dropdown with tree items for a certain tree:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from sitetree.forms import TreeItemForm


class MyTreeItemForm(TreeItemForm):
    """We inherit from TreeItemForm to allow user link some title to sitetree item.
    This form besides `title` field will have `tree_item` dropdown.

    """

    title = forms.CharField()

# We instruct our form to work with `main` aliased sitetree.
# And we set tree item with ID = 2 as initial.
my_form = MyTreeItemForm(tree='main', tree_item=2)

You can also use a well known initial={'tree_item': 2} approach to set an initial sitetree item.

After that deal with that form just as usual.

TreeItemChoiceField

TreeItemChoiceField is what TreeItemForm uses internally to represent sitetree items dropdown, and what used in Admin contrib on sitetree item create/edit pages.

You can inherit from it (and customized it) or use it as it is in your own forms:

1
2
3
4
5
6
7
8
9
from sitetree.fields import TreeItemChoiceField


class MyField(TreeItemChoiceField):

    # We override template used to build select choices.
    template = 'my_templates/tree_combo.html'
    # And override root item representation.
    root_title = '-** Root item **-'