Commit c299303a by Carl Meyer

doc tweaks

parent 0e3f6b7d
django-taggit was original created by Alex Gaynor.
django-taggit was originally created by Alex Gaynor.
The following is a list of much appreciated contributors:
......@@ -7,5 +7,5 @@ fakeempire <adam@fakeempire.com>
Ben Firshman <ben@firshman.co.uk>
Alex Gaynor <alex.gaynor@gmail.com>
Rob Hudson <rob@cogit8.org>
Carl Meyer
Carl Meyer <carl@oddbird.net>
Frank Wiles
......@@ -8,7 +8,7 @@ playing around with the API.
add(*tags)
~~~~~~~~~~
This adds tags to an object, the tags can be either ``Tag`` instances, or
This adds tags to an object. The tags can be either ``Tag`` instances, or
strings::
>>> apple.tags.all()
......@@ -19,7 +19,7 @@ strings::
remove(*tags)
~~~~~~~~~~~~~
Removes a tag from an object, no exception is raised if the object doesn't have
Removes a tag from an object. No exception is raised if the object doesn't have
that tag.
clear()
......@@ -40,4 +40,14 @@ appear, available as the ``num_times`` attribute on each tag. The ``QuerySet``
is ordered by ``num_times``, descending. The ``QuerySet`` is lazily evaluated,
and can be sliced efficiently.
similar_objects()
~~~~~~~~~~~~~~~~~
Returns a list (not a lazy ``QuerySet``) of other objects tagged similarly to
this one, ordered with most similar first. Each object in the list is decorated
with a ``similar_tags`` attribute, the number of tags it shares with this
object.
If using generic tagging (the default), this method searches all tagged
objects. If querying on a model with its own tagging through table, only other
instances of the same model will be returned.
Using a Custom Through Model
============================
By default ``django-taggit`` uses a "through model" with a ``GenericForeignKey``
on it. However, there are some cases where this isn't desirable, for example
if you want the speed and referential guarntees of a real ``ForeignKey``, or if
you have a model with a non-integer primary key. In these cases ``django-taggit``
makes it easy to subsistute your own through model.
You must create your own intermediary model, a subclass of
``taggit.models.TaggedItemBase`` with a foreign key to your content model named
``content_object``, and then pass this intermediary model as the ``through``
argument of ``TaggableManager``::
By default ``django-taggit`` uses a "through model" with a
``GenericForeignKey`` on it. However, there are some cases where this
isn't desirable, for example if you want the speed and referential
guarantees of a real ``ForeignKey``, or if you have a model with a
non-integer primary key. In these cases ``django-taggit`` makes it
easy to substitute your own through model.
Youe intermediary model must be a subclass of
``taggit.models.TaggedItemBase`` with a foreign key to your content
model named ``content_object``. Pass this intermediary model as the
``through`` argument to ``TaggableManager``::
from django.db import models
......@@ -27,5 +28,4 @@ argument of ``TaggableManager``::
tags = TaggableManager(through=TaggedFood)
Once this is done, the API works identically with direct-tagged or
GFK-tagged models.
Once this is done, the API works the same as for GFK-tagged models.
Getting Started
===============
To get started using ``django-taggit`` simply install it ``pip``::
To get started using ``django-taggit`` simply install it with
``pip``::
$ pip install django-taggit
Add it to your project's ``INSTALLED_APPS`` setting.
Add ``"taggit"`` to your project's ``INSTALLED_APPS`` setting.
And then to any model you want tagging on do the following::
......@@ -18,6 +19,3 @@ And then to any model you want tagging on do the following::
# ... fields here
tags = TaggableManager()
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or sign in to comment