Tag Models
Tags are stored in tag models which subclass tagulous.models.TagModel, and use a tagulous.models.TagModelManager. A tag model can either be generated automatically, or you can create a custom model.
Tags in tag models can be protected from automatic deletion when they are not referred to. Initial tags must be loaded using the initial_tags command.
Tag model classes
tagulous.models.TagModel
A TagModel
subclass has the following fields and methods:
name
A CharField
containing the name (string value) of the tag.
Must be unique.
slug
A unique SlugField
, generated automatically from the name when first
saved.
Slugs will support unicode if the TAGULOUS_SLUG_ALLOW_UNICODE
setting is True
. Empty slugs are not allowed; they will default to
underscore. Slug clashes are avoided by adding an integer to the end.
count
An IntegerField
holding the number of times this tag is in use.
protected
A BooleanField
indicating whether this tag should be protected from
deletion when the count reaches 0.
It also has several methods primarily for internal use, but some may be useful:
update_count()
In case you’re doing something weird which causes the count to get out of sync, call this to update the count, and delete the tag if appropriate.
tagulous.models.TagModelManager
A TagModelManager
is the standard manager for a tagulous.models.TagModel; it is a
subclass of the normal Django model manager, but its queries return a
tagulous.models.TagModelQuerySet instead.
It also provides the following additional methods:
filter_or_initial(...)
Calls the normal filter(...)
method, but then adds on any initial tags
which may be missing.
weight(min=1, max=6)
Annotates a weight
field to the tags. This is a weighted count between
the specified min
and max
, which default to TAGULOUS_WEIGHT_MIN
and TAGULOUS_WEIGHT_MAX
(see Settings).
This can be used to generate tag clouds, for example.
tagulous.models.TagModelQuerySet
This is returned by the tagulous.models.TagModelManager; it is a subclass of the normal
Django QuerySet
class, but implements the same additional methods as the
TagModelManager
.
Custom Tag Models
A custom tag model should subclass tagulous.models.TagModel
, so that
Tagulous can find the fields and methods it expects, and so it uses the
appropriate tag model manager and queryset.
A custom tag model is a normal model in every other way, except it can have a TagMeta class to define default options for the class.
There is an example which illustrates how to create a custom tag model.
If you want to use tag trees, you will need to subclass
tagulous.models.TagTreeModel
instead. The only difference is that
there will be extra fields on the model - see Tag Trees for more
details.
TagMeta
The TagMeta
class is a container for tag options, to be used when creating
a custom tag model.
Set any Model Options as class properties. When the model is created by
Python, the options will be available on the tag model class and tag fields
which use it as tag_options
.
Tag fields will not be able to override these options, and SingleTagField
fields will ignore max_count
.
If tree
is specified, it must be appropriate for the base class of the tag
model, eg if tree=True
the tag model must subclass tagulous.models.TagTreeModel -
but if it is not provided it will be set to the correct value.
TagMeta
can be inherited, so it can be set on abstract models. Options in
the TagMeta
of a parent model can be overridden by options in the
TagMeta
of a child model.
Example:
import tagulous
class MyTagModel(tagulous.models.TagModel):
class TagMeta:
initial = 'judo, karate'