Tag Trees
Tags can be nested using tag trees for detailed categorisation, with tags having parents, children and siblings.
Tags in tag trees denote parents using the forward slash character (/
). For
example, Animal/Mammal/Cat
is a Cat
with a parent of Mammal
and
grandparent of Animal
.
To use a slash in a tag name, escape it with a second slash; for example the
tag name Animal/Vegetable
can be entered as Animal//Vegetable
.
A custom tag tree model must be a subclass of tagulous.models.TagTreeModel instead of
the normal tagulous.models.TagModel; for automatically-generated tag models, this is
managed by setting the tree field option to True
.
Tag Tree Model Classes
tagulous.models.TagTreeModel
Because tree tag names are fully qualified (include all ancestors) and unique, there is no difference to normal tags in how they are set or compared.
A TagTreeModel
subclasses tagulous.models.TagModel; it inherits all the normal
fields and methods, and adds the following:
Note
Field values are computed and set automatically in the save()
method -
so don’t try to use them until the tag has been saved.
parent
A ForeignKey
to the parent tag. Tagulous sets this automatically when
saving, creating missing ancestors as needed.
children
The reverse relation manager for parent
, eg mytag.children.all()
.
label
A CharField
containing the name of the tag without its ancestors.
Example: a tag named Animal/Mammal/Cat
has the label Cat
slug
A SlugField
containing the slug for the tag label.
Example: a tag named Animal/Mammal/Cat
has the slug cat
path
A TextField
containing the path for this tag - this slug, plus all ancestor
slugs, separated by the /
character, suitable for use in URLs. Tagulous
sets this automatically when saving.
Example: a tag named Animal/Mammal/Cat
has the path animal/mammal/cat
level
An IntegerField
containing the level of this tag in the tree (starting from
1).
get_ancestors()
Returns a queryset of all ancestors, ordered by level.
get_descendants()
Returns a queryset of all descendants, ordered by level.
get_siblings()
Returns a queryset of all siblings, ordered by name.
This includes the node itself; if you don’t want it in the results, exclude it afterwards, eg:
siblings = node.get_siblings().exclude(pk=node.pk)
tagulous.models.TagTreeModelManager
A TagTreeModelManager
is the standard manager for a tagulous.models.TagTreeModel; it
is a subclass of tagulous.models.TagModelManager so provides those methods, but its
queries return a tagulous.models.TagTreeModelQuerySet instead.
as_nested_list()
Return all tags as a nested list, as lists of (tag, children)
tuples in the format:
[(tag, [child_tuple, ...]), ...]
For example:
[
(level_1_tag, [
(level_2_tag_1, [...]),
(level_2_tag_2, [...]),
]),
(level_1_tag, [...]),
]
Tags will be in alphabetical order.
tagulous.models.TagTreeModelQuerySet
This is returned by the tagulous.models.TagTreeModelManager; it is a subclass of tagulous.models.TagModelQuerySet so provides those methods, but also:
with_ancestors()
Returns a new queryset containing the nodes from the calling queryset, plus their ancestor nodes.
with_descendants()
Returns a new queryset containing the nodes from the calling queryset, plus their descendant nodes.
with_siblings()
Returns a new queryset containing the nodes from the calling queryset, plus theirm sibling nodes.