Installation
Instructions
Install
django-tagulous
:pip install django-tagulous
In your site settings, add Tagulous to
INSTALLED_APPS
and tell Django to use the Tagulous serialization modules:INSTALLED_APPS = ( ... 'tagulous', ) SERIALIZATION_MODULES = { 'xml': 'tagulous.serializers.xml_serializer', 'json': 'tagulous.serializers.json', 'python': 'tagulous.serializers.python', 'yaml': 'tagulous.serializers.pyyaml', }
There are other global Settings you can add here.
Add Tagulous fields to your project - see Models, Forms and Example Usage.
Remember to run manage.py collectstatic
to collect the JavaScript and CSS resources.
When you want to upgrade your Tagulous installation in the future, check Upgrading to see if there are any special actions that you need to take.
Note
If you use MySQL there are some limitations you should be aware of - see:
the setting for max length for limitations of maximum tag lengths
the tag option case_sensitive for limitations of case sensitivity.
Settings
Note
Model and form field options are managed separately by Tag Options.
TAGULOUS_NAME_MAX_LENGTH
,TAGULOUS_SLUG_MAX_LENGTH
,TAGULOUS_LABEL_MAX_LENGTH
Default max lengths for tag models.
Note
When MySQL is using utf8mb4 charset, all unique fields have a max-length of 191 characters, because MySQL max key length in 767 bytes and utf8mb4 reserves 4 bytes per character, thus 767/4 = 191.
If you use MySQL, we therefore recommend the following settings:
TAGULOUS_NAME_MAX_LENGTH=191
Default:
TAGULOUS_NAME_MAX_LENGTH = 255 TAGULOUS_SLUG_MAX_LENGTH = 50 TAGULOUS_LABEL_MAX_LENGTH = TAGULOUS_NAME_MAX_LENGTH
TAGULOUS_SLUG_TRUNCATE_UNIQUE
Number of characters to allow for the numerical suffix when finding a unique slug, ie if set to 5, the slug will be truncated by up to 5 characters to allow for a suffix of up to _9999.
Default:
5
TAGULOUS_SLUG_ALLOW_UNICODE
If
True
unicode will be allowed in slugs. IfFalse
tag slugs will be forced to ASCII.As with Django’s
slugify
, this is off by default.Default:
False
TAGULOUS_AUTOCOMPLETE_JS
,TAGULOUS_ADMIN_AUTOCOMPLETE_JS
List of static JavaScript files required for Tagulous autocomplete. These will be added to the form media when a Tagulous form field is used.
The order is important: the adaptor must appear last in the list, so that it is loaded after its dependencies.
If you use jQuery elsewhere on your site, you may need to remove jquery.js to avoid conflicts.
Default:
TAGULOUS_AUTOCOMPLETE_JS = ( "tagulous/lib/jquery.js", "tagulous/lib/select2-4/js/select2.full.min.js", "tagulous/tagulous.js", "tagulous/adaptor/select2-4.js", )
TAGULOUS_AUTOCOMPLETE_CSS
,TAGULOUS_ADMIN_AUTOCOMPLETE_CSS
List of static CSS files required for Tagulous autocomplete. These will be added to the form media when a Tagulous form field is used.
The default list will use the included version of Select2.
Default:
TAGULOUS_AUTOCOMPLETE_CSS = { 'all': ['tagulous/lib/select2-4/css/select2.min.css'] }
TAGULOUS_AUTOCOMPLETE_SETTINGS
Any settings to pass to the JavaScript via the adaptor. They can be overridden by a field’s autocomplete_settings option.
For example, the select2 control defaults to use the same width as the form element it replaces; you can override this by passing their
width
option (see their docs on appearance) as an autocomplete setting:TAGULOUS_AUTOCOMPLETE_SETTINGS = {"width": "75%"}
If set to
None
, no settings will be passed.Default:
None
TAGULOUS_WEIGHT_MIN
The default minimum value for the weight queryset method.
Default:
1
TAGULOUS_WEIGHT_MAX
The default maximum value for the weight queryset method.
Default:
6
TAGULOUS_ENHANCE_MODELS
Advanced usage - only use this setting if you know what you’re doing.
Tagulous automatically enhances models, managers and querysets to fully support tag fields. This has the theoretical potential for unexpected results, so this setting lets the cautious disable this enhancement.
If you set this to False you will need to manually add Tagulous mixins to your models, managers and querysets.
See Tagged Models for more information.
Default:
True
System checks
Tagulous adds to the Django system check framework with the following:
tagulous.W001
settings.SERIALIZATION_MODULES
has not been configured as expectedA common installation error is to forget to set
SERIALIZATION_MODULES
as described in the installation instructions.This is a straight string comparison. If your serialisation modules don’t match what Tagulous is expecting (you’re subclassing the Tagulous modules, for example), you can disable this warning with the setting:
SILENCED_SYSTEM_CHECKS = ["tagulous.W001"]
Converting to Tagulous
If you’re already using a tagging library which you’d like to replace with Tagulous, freeze the tags into a temporary column, remove the old tagging code, add a new tagulous TagField, then copy the tags back across.
Warning
This hasn’t been tested with your data, so back up your database first, just in case.
Create a schema migration to add a
TextField
to your tagged model, where we’ll temporarily store the tags for that instance.django-taggit
example:class MyModel(models.Model): ... tags = TaggableManager() tags_store = models.TextField(blank=True)
django-tagging
example:class MyModel(models.Model): ... tags_store = models.TextField(blank=True) tagging.register(MyModel)
Create a data migration to copy the tags into the new field as a string.
django-taggit
example:def store_tags(apps, schema_editor): import tagulous model = apps.get_model('myapp', 'MyModel') for obj in model.objects.all(): obj.tags_store = tagulous.utils.render_tags(obj.tags.all()) class Migration(migrations.Migration): operations = [ migrations.RunPython(store_tags) ]
The example for
django-tagging
would be the same, only replaceobj.tags.all()
withobj.tags
.Remove the old tagging code from your model, and create a schema migration to clean up any unused fields or models.
Add a
TagField
to your tagged model and create a schema migration:import tagulous class MyModel(models.Model): tags = tagulous.models.TagField() tags_store = models.TextField(blank=True)
Be careful to set appropriate arguments, ie
blank=True
if some of yourtags_store
fields may be empty.Create a data migration to copy the tags into the new field.
Example:
def load_tags(apps, schema_editor): model = apps.get_model('myapp', 'MyModel') for obj in model.objects.all(): obj.tags = obj.tags_store obj.tags.save() class Migration(migrations.Migration): operations = [ migrations.RunPython(load_tags) ]
Create a schema migration to remove the temporary tag storage field (
tag_store
in these examples)Apply the migrations and start using tagulous