=======
Tagging
=======

Tagging application derived from django-tagging reusable app.

Every tag is represented as Tag model, every tagged model-item (i.e. Article, Photo,
etc.) is represented by TaggedItem model instance.

Tagged items have priority field to separate tags (i.e. tags assigned by staff vs.
tags assigned by page visitors). Two priorities defined by now: PRIMARY_TAG, SECONDARY_TAG.



Tag Cloud
=========

Q: How do I append tag to an object (Article, Photo, etc.)?

A: Tag.objects.add_tag( object, 'interesting', tag_priority=PRIMARY_TAG)


Q: How to get tag cloud for all objects in category?

A: Tag.objects.cloud_for_category( category, priority=PRIMARY_TAG, steps=4, distribution=LOGARITHMIC)


Templates
=========
page/tagging/listing.html
page/tagging/view_publishables.html  (when list of publishable objects associated with tag are viewed)


Template tags
=============

Template tag -- cloud for categorry
-----------------------------------
Retrieves a list of ``Tag`` objects for a given category,
creates template variable ``varname``.

Usage::

   {% tag_cloud_for_category [model] as [varname] %}

The category is specified by template variable or by slug.

Extended usage::

   {% tag_cloud_for_category [category] 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:

   ``priority``
      Constant described by string. Tag priority.
      Possible values: PRIMARY_TAG, SECONDARY_TAG

   ``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_category category_variable as widget_tags %}
   {% tag_cloud_for_category "slug-johohooo" as widget_tags %}
   {% tag_cloud_for_category category_variable as widget_tags with priority=PRIMARY_TAG steps=9 min_count=3 distribution=log %}



Template 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 %}


Template tag -- 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 %}


Settings
========

FORCE_LOWERCASE_TAGS  ... lower case when saving new tags (by calling Tag.objects.add_tag)

