Installation
Requirements
These packages are required:
- Django 1.4.2 to 1.11, on Python 2.7 and 3.3 to 3.6.
These packages are recommended, but optional:
- unidecode
- django-compressor or similar, to optimise static files
- South 1.0.2 or later, to manage database migrations (if using Django 1.6 or earlier)
If you are replacing an existing tagging solution, follow the Instructions, then read Converting to Tagulous.
Instructions
-
Install
django-tagulous
:pip install django-tagulous
or to install with improved unicode support in slugs (installs
unidecode
- seeslug
for more details):pip install django-tagulous[i18n]
-
In your site settings, add Tagulous to
INSTALLED_APPS
:INSTALLED_APPS = ( ... 'tagulous', )
In the same file, tell Django to use the Tagulous serialization modules, so that Django can serialize tag fields (for fixtures etc):
SERIALIZATION_MODULES = { 'xml': 'tagulous.serializers.xml_serializer', 'json': 'tagulous.serializers.json', 'python': 'tagulous.serializers.python', 'yaml': 'tagulous.serializers.pyyaml', }
You may also want to change some Tagulous settings here - see the global max length Settings for details.
You are now ready to add Tagulous fields to your models - see Models, Forms and Example Usage.
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.
Settings
-
TAGULOUS_NAME_MAX_LENGTH
TAGULOUS_SLUG_MAX_LENGTH
TAGULOUS_LABEL_MAX_LENGTH
-
Default max length for tag models.
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_AUTOCOMPLETE_JS
-
List of paths under
STATIC_URL
for any JavaScript files which are 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 versions of jQuery and Select2, with the tagulous Select2 adaptor. See Autocomplete Adaptors for information about using other adaptors, or writing your own.
The order is important: the adaptor must appear last in the list, so that it is loaded after its dependencies.
Because a typical Tagulous installation will use multiple JavaScript files, you may want to use something like django-compressor to combine them into a single file to optimise requests.
Default:
TAGULOUS_AUTOCOMPLETE_JS = ( 'tagulous/lib/jquery.js', 'tagulous/lib/select2-3/select2.min.js', 'tagulous/tagulous.js', 'tagulous/adaptor/select2.js', )
-
TAGULOUS_AUTOCOMPLETE_CSS
-
List of paths under
STATIC_URL
to any CSS files which are 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-3/select2.css'] }
-
TAGULOUS_AUTOCOMPLETE_SETTINGS
-
Any settings which you want to override in the default adaptor. These will be converted to a JSON value and embedded in the HTML field's
data-tag-options
attribute. They can be overridden by a field's autocomplete_settings option.If set to
None
, no settings will be added to the HTML field.Default:
None
-
TAGULOUS_ADMIN_AUTOCOMPLETE_JS
-
List of paths under
STATIC_URL
to any javascript files which are required for the admin site. This lets you configure your public and admin sites separately if you need to.If your autocomplete library uses jQuery and you want to use the Django admin's version, you will need to set
window.jQuery = django.jQuery;
before loading the autocomplete javascript.By default this will be the same as you have set for
TAGULOUS_AUTOCOMPLETE_JS
.Default: value of setting
TAGULOUS_AUTOCOMPLETE_JS
-
TAGULOUS_ADMIN_AUTOCOMPLETE_CSS
-
List of paths under
STATIC_URL
to any CSS files which are required for the admin site. This lets you configure your public and admin sites separately if you need to.By default this will be the same as you have set for
TAGULOUS_AUTOCOMPLETE_CSS
.Default: value of setting
TAGULOUS_AUTOCOMPLETE_CSS
-
TAGULOUS_ADMIN_AUTOCOMPLETE_SETTINGS
-
Admin settings for overriding the adaptor defaults.
By default this will be the same as you have set for
TAGULOUS_AUTOCOMPLETE_SETTINGS
.Default: value of setting
TAGULOUS_AUTOCOMPLETE_SETTINGS
-
TAGULOUS_ENHANCE_MODELS
-
Feature flag to automatically enhance models, managers and querysets to fully support tag fields.
In most situations Tagulous is able to sprinkle its syntactic sugar without intefering with third-party code. However, there are a few places in Django's darkest magical depths of its model code that it needs a helping hand to understand the tag fields. When this setting is
True
, any models which use tag fields will automatically be enhanced to make this happen, along with their managers and querysets.If you set this to
False
, Tagulous will still work, but certain aspects may not work as you would expect - you should consider manually enhancing your models, managers and querysets.See Tagged Models for more information.
Default:
True
-
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
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.
-
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 using South:def forwards(self, orm): import tagulous for obj in orm['myapp.MyModel'].objects.all(): obj.tags_store = tagulous.utils.render_tags(obj.tags.all())
django-taggit
example using Django migrations: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 using South:
def forwards(self, orm): for obj in orm['myapp.MyModel'].objects.all(): obj.tags = obj.tags_store obj.tags.save()
Example using Django migrations:
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