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.
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.