============== Django Tagging ============== A generic tagging application for `Django`_ projects, which allows association of a number of tags with any ``Model`` instance and makes retrieval of tags simple. .. _`Django`: http://www.djangoproject.com Installation ============ Downloading django-tagging -------------------------- There are two options for downloading; one is to download the latest packaged version from http://code.google.com/p/django-tagging/ and unpack it; inside is a script called setup.py. Type this command:: python setup.py install ...and the package will install automatically. The other method is to perform a Subversion checkout from somewhere on your Python path: svn checkout http://django-tagging.googlecode.com/svn/trunk/tagging/ Keep in mind that the current code in SVN may be different from the packaged release, and may contain bugs and backwards-incompatible changes. Using django-tagging in your projects ------------------------------------- Once you've downloaded django-tagging and want to use it in your projects, 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 tags to lowercase before they are saved to the database. 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 consisting only of unicode alphanumeric characters, numbers, underscores and hyphens. 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. Valid tag names may contain unicode alphanumeric characters, numbers, underscores or hyphens. Multiple tag names may be specified, separated by any number of commas and spaces. 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. Valid tag names may contain unicode alphanumeric characters, numbers, underscores or hyphens. * ``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 ----------- 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 object. * ``object_id`` -- The id of the associated object. * ``object`` -- The associated object. 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_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`` helper function:: >>> 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: get_tag_name_list(tags_names) ----------------------------- Finds tag names in the given string and return them in a list. 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) ---------------------------------------------------------------------- Adds a ``font_size`` attribute to each tag given 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 either ``tagging.utils.LOGARITHMIC`` (default) or ``tagging.utils.LINEAR``. The algorithm to scale the tags logarithmically is from a blog post by Anders Pearson, `Scaling tag clouds`_. .. _`Scaling tag clouds`: http://thraxil.com/users/anders/posts/2005/12/13/scaling-tag-clouds/ 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, separated by a single comma, a single space or a comma followed by a space. When you generate a form for one of your models automatically, using the ``form_for_model`` or ``form_for_instance`` functions provided by the newforms library, 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 __str__(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 ============= **New in django-tagging development version** The ``tagging.views`` module contains views to handle common display ogic related to tagging. The following sample URLconf demonstrates using a generic view to list items of a particular model 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('', (r'^widgets/tag/(?P[^/]+(?u))/$', tagged_object_list, dict(model=Widget, paginate_by=10, allow_empty=True, template_object_name='widget')), ) ``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:** * ``tag``: The ``Tag`` instance for the given tag. Please refer to the `object_list documentation`_ for additional template context variables which may be provided. .. _`object_list documentation`: http://www.djangoproject.com/documentation/generic_views/#django-views-generic-list-detail-object-list 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 tags associated with the given model and stores them in a context variable. The model is specified in ``[appname].[modelname]`` format. 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. Example usage:: {% tags_for_model products.Widget as widget_tags %} {% tags_for_model products.Widget as widget_tags with counts %} tags_for_object ~~~~~~~~~~~~~~~ Retrieves a list of tags associated with an object and stores them in a context variable. Example usage:: {% tags_for_object widget as tag_list %} tagged_objects ~~~~~~~~~~~~~~ Retrieves a list of objects for a given model which are tagged with a given tag and stores them in a context variable. The tag must be an instance of a ``Tag``, not the name of a tag. The model is specified in ``[appname].[modelname]`` format. Example usage:: {% tagged_objects house_tag in products.Widget as widgets %}