============== Django Tagging ============== A generic tagging application for `Django`_ projects, which allows association of a number of tags with any Django model instance and makes retrieval of tags simple. .. _`Django`: http://www.djangoproject.com .. contents:: :depth: 3 Installation ============ Installing an official release ------------------------------ Official releases are made available from http://code.google.com/p/django-tagging/ Source distribution ~~~~~~~~~~~~~~~~~~~ Download the .zip distribution file and unpack it. Inside is a script named ``setup.py``. Enter this command:: python setup.py install ...and the package will install automatically. Windows installer ~~~~~~~~~~~~~~~~~ A Windows installer is also made available - download the .exe distribution file and launch it to install the application. An uninstaller will also be created, accessible through Add/Remove Programs in your Control Panel. Installing the development version ---------------------------------- Alternatively, if you'd like to update Django Tagging occasionally to pick up the latest bug fixes and enhancements before they make it into an offical release, perform a `Subversion`_ checkout instead. The following command will check the application's development branch out to an ``mptt-trunk`` directory:: svn checkout http://django-tagging.googlecode.com/svn/trunk/ tagging-trunk Add the resulting folder to your `PYTHONPATH`_ or symlink (`junction`_, if you're on Windows) the ``tagging`` directory inside it into a directory which is on your PYTHONPATH, such as your Python installation's ``site-packages`` directory. You can verify that the application is available on your PYTHONPATH by opening a Python interpreter and entering the following commands:: >>> import tagging >>> tagging.VERSION (0, 2, 'pre') When you want to update your copy of the Django Tagging source code, run the command ``svn update`` from within the ``tagging-trunk`` directory. .. caution:: The development version may contain bugs which are not present in the release version and introduce backwards-incompatible changes. If you're tracking trunk, keep an eye on the `CHANGELOG`_ and the `backwards-incompatible changes wiki page`_ before you update your copy of the source code. .. _`Subversion`: http://subversion.tigris.org .. _`PYTHONPATH`: http://docs.python.org/tut/node8.html#SECTION008110000000000000000 .. _`junction`: http://www.microsoft.com/technet/sysinternals/FileAndDisk/Junction.mspx .. _`CHANGELOG`: http://django-tagging.googlecode.com/svn/trunk/CHANGELOG.txt .. _`backwards-incompatible changes wiki page`: http://code.google.com/p/django-tagging/wiki/BackwardsIncompatibleChanges Using Django Tagging in your applications ----------------------------------------- Once you've installed Django Tagging and want to use it in your Django applications, do the following: 1. Put ``'tagging'`` in your ``INSTALLED_APPS`` setting. 2. Run the command ``manage.py syncdb``. The ``syncdb`` command creates the necessary database tables and creates permission objects for all installed apps that need them. That's it! Settings ======== Some of Django Tagging's behaviour may be configured by adding the appropriate settings to your project's settings file. The following settings are available: FORCE_LOWERCASE_TAGS -------------------- Default: ``False`` A boolean that turns on/off forcing of all tag names to lowercase before they are saved to the database. MAX_TAG_LENGTH -------------- Default: ``50`` An integer which specifies the maxiumum length which any tag is allowed to have. This is used for validation in the ``django.contrib.admin`` application and in any ``newforms`` forms automatically generated using ``ModelForm``. Tags ==== Tags are represented by the ``Tag`` model, which lives in the ``tagging.models`` module. API reference ------------- Fields ~~~~~~ ``Tag`` objects have the following fields: * ``name`` -- The name of the tag. This is a unique value. Manager functions ~~~~~~~~~~~~~~~~~ The ``Tag`` model has a custom manager which has the following helper functions: * ``update_tags(obj, tag_names)`` -- updates tags associated with an object. ``tag_names`` is a string containing tag names with which ``obj`` should be tagged. If ``tag_names`` is ``None`` or ``''``, the object's tags will be cleared. * ``add_tag(obj, tag_name)`` -- associates a tag with an an object. ``tag_name`` is a string containing a tag name with which ``obj`` should be tagged. * ``get_for_object(obj)`` -- returns a ``QuerySet`` containing all ``Tag`` objects associated with ``obj``. * ``usage_for_model(Model, counts=False, min_count=None, filters=None)`` -- returns a list of ``Tag`` objects associated with instances of ``Model``. If ``counts`` is ``True``, a ``count`` attribute will be added to each tag, indicating how many times it has been associated with instances of ``Model``. If ``min_count`` is given, only tags which have a ``count`` greater than or equal to ``min_count`` will be returned. Passing a value for ``min_count`` implies ``counts=True``. To limit the tags (and counts, if specified) returned to those used by a subset of the model's instances, pass a dictionary of field lookups to be applied to ``Model`` as the ``filters`` argument. * ``related_for_model(tags, Model, counts=False, min_count=None)`` -- returns a list of tags related to a given list of tags - that is, other tags used by items which have all the given tags. If ``counts`` is ``True``, a ``count`` attribute will be added to each tag, indicating the number of items which have it in addition to the given list of tags. If ``min_count`` is given, only tags which have a ``count`` greater than or equal to ``min_count`` will be returned. Passing a value for ``min_count`` implies ``counts=True``. * ``cloud_for_model(Model, steps=4, distribution=LOGARITHMIC, filters=None, min_count=None)`` -- returns a list of the distinct ``Tag`` objects associated with instances of ``Model``, each having a ``count`` attribute as above and an additional ``font_size`` attribute, for use in creation of a tag cloud (a type of weighted list). ``steps`` defines the number of font sizes available - ``font_size`` may be an integer between ``1`` and ``steps``, inclusive. ``distribution`` defines the type of font size distribution algorithm which will be used - logarithmic or linear. It must be either ``tagging.utils.LOGARITHMIC`` or ``tagging.utils.LINEAR``. To limit the tags displayed in the cloud to those associated with a subset of the Model's instances, pass a dictionary of field lookups to be applied to the given Model as the ``filters`` argument. To limit the tags displayed in the cloud to those with a ``count`` greater than or equal to ``min_count``, pass a value for the ``min_count`` argument. Basic usage ----------- Tag input ~~~~~~~~~ Tag input from users is treated as follows: * If the tag input doesn't contain any commas or double quotes, it is simply treated as a space-delimited list of tag names. * If the tag input does contain either of these characters, we parse the input like so: * Groups of characters which appear between double quotes take precedence as multi-word tags (so double quoted tag names may contain commas). An unclosed double quote will be ignored. * For the remaining input, if there are any unquoted commas in the input, the remainder will be treated as comma-delimited. Otherwise, it will be treated as space-delimited. Examples: ====================== ======================================= ================================================ Tag input Resulting tag names Notes ====================== ======================================= ================================================ apple ball cat [``apple``], [``ball``], [``cat``] No commas or quotes, so space delimited apple, ball cat [``apple``], [``ball cat``] Comma present, so comma delimited "apple, ball" cat dog [``apple, ball``], [``cat``], [``dog``] All commas are quoted, so space delimited "apple, ball", cat dog [``apple, ball``], [``cat dog``] Contains an unquoted comma, so comma delimited apple "ball cat" dog [``apple``], [``ball cat``], [``dog``] No commas, so space delimited "apple" "ball dog [``apple``], [``ball``], [``dog``] Unclosed double quote is ignored ====================== ======================================= ================================================ Tagging objects and retrieving an object's tags ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Objects may be tagged using the ``update_tags`` helper function:: >>> from shop.apps.products.models import Widget >>> from tagging.models import Tag >>> widget = Widget.objects.get(pk=1) >>> Tag.objects.update_tags(widget, 'house thing') Retrieve tags for an object using the ``get_for_object`` helper function:: >>> Tag.objects.get_for_object(widget) [, ] Tags are created, associated and unassociated accordingly when you use ``update_tags`` and ``add_tags``:: >>> Tag.objects.update_tags(widget, 'house monkey') >>> Tag.objects.get_for_object(widget) [, ] >>> Tag.objects.add_tag(widget, 'tiles') >>> Tag.objects.get_for_object(widget) [, , ] Clear an object's tags by passing ``None`` or ``''`` to ``update_tags``:: >>> Tag.objects.update_tags(widget, None) >>> Tag.objects.get_for_object(widget) [] Retrieving tags used by a particular model ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ To retrieve all tags used for a particular model, use the ``get_for_model`` helper function:: >>> widget1 = Widget.objects.get(pk=1) >>> Tag.objects.update_tags(widget1, 'house thing') >>> widget2 = Widget.objects.get(pk=2) >>> Tag.objects.update_tags(widget2, 'cheese toast house') >>> Tag.objects.usage_for_model(Widget) [, , , ] To get a count of how many times each tag was used for a particular model, pass in ``True`` for the ``counts`` argument:: >>> tags = Tag.objects.usage_for_model(Widget, counts=True) >>> [(tag.name, tag.count) for tag in tags] [('cheese', 1), ('house', 2), ('thing', 1), ('toast', 1)] To get counts and limit the tags returned to those with counts above a certain size, pass in a ``min_count`` argument:: >>> tags = Tag.objects.usage_for_model(Widget, min_count=2) >>> [(tag.name, tag.count) for tag in tags] [('house', 2)] You can also specify a dictionary of `field lookups`_ to be used to restrict the tags and counts returned based on a subset of the model's instances. For example, the following would retrieve all tags used on Widgets created by a user named Alan which have a size greater than 99:: >>> Tag.objects.usage_for_model(Widget, filters=dict(size__gt=99, user__username='Alan')) .. _`field lookups`: http://www.djangoproject.com/documentation/db-api/#field-lookups Tagged items ============ The relationship between a ``Tag`` and an object is represented by the ``TaggedItem`` model, which lives in the ``tagging.models`` module. API reference ------------- Fields ~~~~~~ ``TaggedItem`` objects have the following fields: * ``tag`` -- The ``Tag`` an object is associated with. * ``content_type`` -- The ``ContentType`` of the associated model instance. * ``object_id`` -- The id of the associated object. * ``object`` -- The associated object itself, accessible via the Generic Relations API. Manager functions ~~~~~~~~~~~~~~~~~ The ``TaggedItem`` model has a custom manager which has the following helper functions: * ``get_by_model(Model, tag)`` -- If ``tag`` is an instance of a ``Tag``, returns a ``QuerySet`` containing all instances of ``Model`` which are tagged with it. If ``tag`` is a list of tags, returns a ``QuerySet`` containing all instances of ``Model`` which are tagged with every tag in the list. * ``get_intersection_by_model(Model, tags)`` -- Returns a ``QuerySet`` containing all instances of ``Model`` which are tagged with every tag in the list. ``get_by_model`` will call this function behind the scenes when you pass it a list, so it's recommended that you use ``get_by_model`` instead of calling this function directly. * ``get_union_by_model(Model, tags)`` -- Returns a ``QuerySet`` containing all instances of ``Model`` which are tagged with any tag in the list. * ``get_related(obj, Model, num=None)`` - Returns instances of ``Model`` which share tags with the model instance ``obj``, ordered by the number of shared tags in descending order. If ``num`` is given, a maximum of ``num`` instances will be returned. Basic usage ----------- Retrieving tagged objects ~~~~~~~~~~~~~~~~~~~~~~~~~ Objects may be retrieved based on their tags using the ``get_by_model`` manager method:: >>> from shop.apps.products.models import Widget >>> from tagging.models import Tag >>> house_tag = Tag.objects.get(name='house') >>> TaggedItem.objects.get_by_model(Widget, house_tag) [, ] Passing a list of tags to ``get_by_model`` returns an intersection of objects which have those tags, i.e. tag1 AND tag2 ... AND tagN:: >>> thing_tag = Tag.objects.get(name='thing') >>> TaggedItem.objects.get_by_model(Widget, [house_tag, thing_tag]) [] Functions which take tags are flexible when it comes to tag input:: >>> TaggedItem.objects.get_by_model(Widget, Tag.objects.filter(name__in=['house', 'thing'])) [] >>> TaggedItem.objects.get_by_model(Widget, 'house thing') [] >>> TaggedItem.objects.get_by_model(Widget, ['house', 'thing']) [] Utilities ========= Tag-related utility functions are defined in the ``tagging.utils`` module: ``parse_tag_input(input)`` -------------------------- Parses tag input, with multiple word input being activated and delineated by commas and double quotes. Quotes take precedence, so they may contain commas. Returns a sorted list of unique tag names. See `tag input`_ for more details. ``edit_string_for_tags(tags)`` ------------------------------ Given list of ``Tag`` instances, creates a string representation of the list suitable for editing by the user, such that submitting the given string representation back without changing it will give the same list of tags. Tag names which contain commas will be double quoted. If any tag name which isn't being quoted contains whitespace, the resulting string of tag names will be comma-delimited, otherwise it will be space-delimited. ``get_tag_list(tags)`` ---------------------- Utility function for accepting tag input in a flexible manner. If a ``Tag`` object is given, it will be returned in a list as its single occupant. If given, the tag names in the following will be used to create a ``Tag`` ``QuerySet``: * A string, which may contain multiple tag names. * A list or tuple of strings corresponding to tag names. * A list or tuple of integers corresponding to tag ids. If given, the following will be returned as-is: * A list or tuple of ``Tag`` objects. * A ``Tag`` ``QuerySet``. ``calculate_cloud(tags, steps=4, distribution=tagging.utils.LOGARITHMIC)`` -------------------------------------------------------------------------- Add a ``font_size`` attribute to each tag according to the frequency of its use, as indicated by its ``count`` attribute. ``steps`` defines the range of font sizes - ``font_size`` will be an integer between 1 and ``steps`` (inclusive). ``distribution`` defines the type of font size distribution algorithm which will be used - logarithmic or linear. It must be one of ``tagging.utils.LOGARITHMIC`` or ``tagging.utils.LINEAR``. Model Fields ============ The ``tagging.fields`` module contains fields which make it easy to integrate tagging into your models and into the ``django.contrib.admin`` application. Field types ----------- ``TagField`` ~~~~~~~~~~~~ A ``CharField`` that actually works as a relationship to tags "under the hood". Using this example model:: class Link(models.Model): ... tags = TagField() Setting tags:: >>> l = Link.objects.get(...) >>> l.tags = 'tag1 tag2 tag3' Getting tags for an instance:: >>> l.tags 'tag1 tag2 tag3' Getting tags for a model - i.e. all tags used by all instances of the model:: >>> Link.tags 'tag1 tag2 tag3 tag4 tag5' This field will also validate that it has been given a valid list of tag names, separated by a single comma, a single space or a comma followed by a space, using the ``isTagList`` validator from ``tagging.validators``. Form fields =========== The ``tagging.forms`` module contains a ``Field`` for use with Django's `newforms library`_ which takes care of validating tag name input when used in your forms. .. _`newforms library`: http://www.djangoproject.com/documentation/newforms/ Field types ----------- ``TagField`` ~~~~~~~~~~~~ A form ``Field`` which is displayed as a single-line text input, which validates that the input it receives is a valid list of tag names. When you generate a form for one of your models automatically, using the ``ModelForm`` class provided by newforms, any ``tagging.fields.TagField`` fields in your model will automatically be represented by a ``tagging.forms.TagField`` in the generated form. Simplified tagging and retrieval of tags with properties ======================================================== If you're not using ``TagField``, a useful method for simplifying tagging and retrieval of tags for your models is to set up a property:: from django.db import models from tagging.models import Tag class MyModel(models.Model): name = models.CharField(maxlength=100) tag_list = models.CharField(maxlength=255) def save(self): super(MyModel, self).save() self.tags = self.tag_list def _get_tags(self): return Tag.objects.get_for_object(self) def _set_tags(self, tag_list): Tag.objects.update_tags(self, tag_list) tags = property(_get_tags, _set_tags) def __unicode__(self): return self.name Once you've set this up, you can access and set tags in a fairly natural way:: >>> obj = MyModel.objects.get(pk=1) >>> obj.tags = 'foo bar' >>> obj.tags [, ] Remember that ``obj.tags`` will return a ``QuerySet``, so you can perform further filtering on it, should you need to. Generic views ============= The ``tagging.views`` module contains views to handle simple cases of common display logic related to tagging. ``tagging.views.tagged_object_list`` ------------------------------------ **Description:** A view that displays a list of objects for a given model which have a given tag. This is a thin wrapper around the ``django.views.generic.list_detail.object_list`` view, which takes a model and a tag as its arguments (in addition to the other optional arguments supported by ``object_list``), building the appropriate ``QuerySet`` for you instead of expecting one to be passed in. **Required arguments:** * ``model``: The Django model class of the object that will be listed. * ``tag``: The tag which objects of the given model must have in order to be listed. **Optional arguments:** Please refer to the `object_list documentation`_ for additional optional arguments which may be given. * ``related_tags``: If ``True``, a ``related_tags`` context variable will also contain tags related to the given tag for the given model. * ``related_tag_counts``: If ``True`` and ``related_tags`` is ``True``, each related tag will have a ``count`` attribute indicating the number of items which have it in addition to the given tag. **Template context:** Please refer to the `object_list documentation`_ for additional template context variables which may be provided. * ``tag``: The ``Tag`` instance for the given tag. .. _`object_list documentation`: http://www.djangoproject.com/documentation/generic_views/#django-views-generic-list-detail-object-list Example usage ~~~~~~~~~~~~~ The following sample URLconf demonstrates using this generic view to list items of a particular model class which have a given tag:: from django.conf.urls.defaults import * from tagging.views import tagged_object_list from shop.apps.products.models import Widget urlpatterns = patterns('', url(r'^widgets/tag/(?P[^/]+)/$', tagged_object_list, dict(model=Widget, paginate_by=10, allow_empty=True, template_object_name='widget'), name='widget_tag_detail'), ) Template tags ============= The ``tagging.templatetags.tagging_tags`` module defines a number of template tags which may be used to work with tags. Tag reference ------------- tags_for_model ~~~~~~~~~~~~~~ Retrieves a list of ``Tag`` objects associated with a given model and stores them in a context variable. Usage:: {% tags_for_model [model] as [varname] %} The model is specified in ``[appname].[modelname]`` format. Extended usage:: {% tags_for_model [model] as [varname] with counts %} If specified - by providing extra ``with counts`` arguments - adds a ``count`` attribute to each tag containing the number of instances of the given model which have been tagged with it. Examples:: {% tags_for_model products.Widget as widget_tags %} {% tags_for_model products.Widget as widget_tags with counts %} tag_cloud_for_model ~~~~~~~~~~~~~~~~~~~ Retrieves a list of ``Tag`` objects for a given model, with tag cloud attributes set, and stores them in a context variable. Usage:: {% tag_cloud_for_model [model] as [varname] %} The model is specified in ``[appname].[modelname]`` format. Extended usage:: {% tag_cloud_for_model [model] as [varname] with [options] %} Extra options can be provided after an optional ``with`` argument, with each option being specified in ``[name]=[value]`` format. Valid extra options are: ``steps`` Integer. Defines the range of font sizes. ``min_count`` Integer. Defines the minimum number of times a tag must have been used to appear in the cloud. ``distribution`` One of ``linear`` or ``log``. Defines the font-size distribution algorithm to use when generating the tag cloud. Examples:: {% tag_cloud_for_model products.Widget as widget_tags %} {% tag_cloud_for_model products.Widget as widget_tags with steps=9 min_count=3 distribution=log %} tags_for_object ~~~~~~~~~~~~~~~ Retrieves a list of ``Tag`` objects associated with an object and stores them in a context variable. Usage:: {% tags_for_object [object] as [varname] %} Example:: {% tags_for_object foo_object as tag_list %} tagged_objects ~~~~~~~~~~~~~~ Retrieves a list of instances of a given model which are tagged with a given ``Tag`` and stores them in a context variable. Usage:: {% tagged_objects [tag] in [model] as [varname] %} The model is specified in ``[appname].[modelname]`` format. The tag must be an instance of a ``Tag``, not the name of a tag. Example:: {% tagged_objects comedy_tag in tv.Show as comedies %}