From 3b9f21a55fed735652716e63fedabad87899be81 Mon Sep 17 00:00:00 2001 From: SVN-Git Migration Date: Thu, 8 Oct 2015 11:51:45 -0700 Subject: Imported Upstream version 0.2.1 --- docs/overview.txt | 1347 +++++++++++++++++++++++++++++------------------------ 1 file changed, 751 insertions(+), 596 deletions(-) (limited to 'docs') diff --git a/docs/overview.txt b/docs/overview.txt index 61cb086..c5c72e6 100644 --- a/docs/overview.txt +++ b/docs/overview.txt @@ -1,596 +1,751 @@ -============== -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 %} \ No newline at end of file +============== +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 %} -- cgit v1.2.3