Tag model classes
TagModel subclass has the following fields and methods:
CharField containing the name (string value) of the tag.
Must be unique.
SlugField, generated automatically from the name when first saved.
unidecode is installed, Tagulous will use it to make a best-guess conversion of non-ascii characters to something similar in ascii which will be safe for a slug field. If
unidecode is not installed, Tagulous will strip diacritical marks from extended ascii characters, but then just convert any remaining non-ascii characters to underscores. In most cases either option will be adequate for European languages, but if your tags frequently contain non-European characters you'll have less slug clashes if you use
IntegerField holding the number of times this tag is in use.
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:
Return a list of instances of other models which refer to this tag; see the API for more details
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.
Merge the specified tags into this tag.
tags can be a queryset, list of tags or tag names, or a tag string.
It also provides the following additional methods:
Calls the normal
filter(...) method, but then adds on any initial tags which may be missing.
weight field to the tags. This is a weighted count between the specified
max, which default to
TAGULOUS_WEIGHT_MAX (see Settings).
This can be used to generate tag clouds, for example.
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
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 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 fields will not be able to override these options, and
SingleTagField fields will ignore
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.
import tagulous class MyTagModel(tagulous.models.TagModel): class TagMeta: initial = 'judo, karate'
The tag model keeps a count of how many times each tag is referenced. When the tag count reaches
0, the tag will be deleted unless its
protected field is
True, or the
protect_all option has been used.
Loading initial tags
Initial tags must be loaded using the
initial_tags management command. You can either load all initial tags in your site by not passing in any arguments, or specify an app, model or field to load:
python manage.py initial_tags [<app_name>[.<model_name>[.<field_name>]]]
- Tags which are new will be created
- Tags which have been deleted will be recreated
- Tags which exist will be untouched