diff options
Diffstat (limited to 'docs/overview.txt')
| -rw-r--r-- | docs/overview.txt | 751 |
1 files changed, 751 insertions, 0 deletions
diff --git a/docs/overview.txt b/docs/overview.txt new file mode 100644 index 0000000..c5c72e6 --- /dev/null +++ b/docs/overview.txt @@ -0,0 +1,751 @@ +==============
+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)
+ [<Tag: house>, <Tag: thing>]
+
+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: house>, <Tag: monkey>]
+ >>> Tag.objects.add_tag(widget, 'tiles')
+ >>> Tag.objects.get_for_object(widget)
+ [<Tag: house>, <Tag: monkey>, <Tag: tiles>]
+
+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)
+ [<Tag: cheese>, <Tag: house>, <Tag: thing>, <Tag: toast>]
+
+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)
+ [<Widget: pk=1>, <Widget: pk=2>]
+
+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])
+ [<Widget: pk=1>]
+
+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']))
+ [<Widget: pk=1>]
+ >>> TaggedItem.objects.get_by_model(Widget, 'house thing')
+ [<Widget: pk=1>]
+ >>> TaggedItem.objects.get_by_model(Widget, ['house', 'thing'])
+ [<Widget: pk=1>]
+
+
+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
+ [<Tag: bar>, <Tag: foo>]
+
+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<tag>[^/]+)/$',
+ 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 %}
|