Fixed #4234 -- Added docs/contenttypes. Thanks, ubernostrum

git-svn-id: http://code.djangoproject.com/svn/django/trunk@6302 bcc190cf-cafb-0310-a4f2-bffc1f526a37

docs/contenttypes.txt

@@ -0,0 +1,258 @@
+==========================
+The contenttypes framework
+==========================
+
+Django includes a "contenttypes" application that can track all of
+the models installed in your Django-powered project, providing a
+high-level, generic interface for working with your models.
+
+Overview
+========
+
+At the heart of the contenttypes application is the ``ContentType``
+model, which lives at
+``django.contrib.contenttypes.models.ContentType``. Instances of
+``ContentType`` represent and store information about the models
+installed in your project, and new instances of ``ContentType`` are
+automatically created whenever new models are installed.
+
+Instances of ``ContentType`` have methods for returning the model
+classes they represent and for querying objects from those models.
+``ContentType`` also has a `custom manager`_ that adds methods for
+working with ``ContentType`` and for obtaining instances of
+``ContentType`` for a particular model.
+
+Relations between your models and ``ContentType`` can also be used to
+enable "generic" relationships between an instance of one of your
+models and instances of any model you have installed.
+
+.. _custom manager: ../model-api/#custom-managers
+
+Installing the contenttypes framework
+=====================================
+
+The contenttypes framework is included in the default
+``INSTALLED_APPS`` list created by ``django-admin.py startproject``,
+but if you've removed it or if you manually set up your
+``INSTALLED_APPS`` list, you can enable it by adding
+``'django.contrib.contenttypes'`` to your ``INSTALLED_APPS`` setting.
+
+It's generally a good idea to have the contenttypes framework
+installed; several of Django's other bundled applications require it:
+
+    * The admin application uses it to log the history of each object
+      added or changed through the admin interface.
+
+    * Django's `authentication framework`_ uses it to tie user permissions
+      to specific models.
+
+    * Django's comments system (``django.contrib.comments``) uses it to
+      "attach" comments to any installed model.
+
+.. _authentication framework: ../authentication/
+
+The ``ContentType`` model
+=========================
+
+Each instance of ``ContentType`` has three fields which, taken
+together, uniquely describe an installed model:
+
+    ``app_label``
+        The name of the application the model is part of. This is taken from
+        the ``app_label`` attribute of the model, and includes only the *last*
+        part of the application's Python import path;
+        "django.contrib.contenttypes", for example, becomes an ``app_label``
+        of "contenttypes".
+
+    ``model``
+        The name of the model class.
+
+    ``name``
+        The human-readable name of the model. This is taken from
+        `the verbose_name attribute`_ of the model.
+
+Let's look at an example to see how this works. If you already have
+the contenttypes application installed, and then add `the sites
+application`_ to your ``INSTALLED_APPS`` setting and run ``manage.py
+syncdb`` to install it, the model ``django.contrib.sites.models.Site``
+will be installed into your database. Along with it a new instance
+of ``ContentType`` will be created with the following values:
+
+    * ``app_label`` will be set to ``'sites'`` (the last part of the Python
+      path "django.contrib.sites").
+
+    * ``model`` will be set to ``'site'``.
+
+    * ``name`` will be set to ``'site'``.
+
+.. _the verbose_name attribute: ../model-api/#verbose_name
+.. _the sites application: ../sites/
+
+Methods on ``ContentType`` instances
+====================================
+
+Each ``ContentType`` instance has methods that allow you to get from a
+``ContentType`` instance to the model it represents, or to retrieve objects
+from that model:
+
+    ``get_object_for_this_type(**kwargs)``
+        Takes a set of valid `lookup arguments`_ for the model the
+        ``ContentType`` represents, and does `a get() lookup`_ on that
+        model, returning the corresponding object.
+
+    ``model_class()``
+        Returns the model class represented by this ``ContentType``
+        instance.
+
+For example, we could look up the ``ContentType`` for the ``User`` model::
+
+    >>> from django.contrib.contenttypes.models import ContentType
+    >>> user_type = ContentType.objects.get(app_label="auth", model="user")
+    >>> user_type
+    <ContentType: user>
+
+And then use it to query for a particular ``User``, or to get access
+to the ``User`` model class::
+
+    >>> user_type.model_class()
+    <class 'django.contrib.auth.models.User'>
+    >>> user_type.get_object_for_this_type(username='Guido')
+    <User: Guido>
+
+Together, ``get_object_for_this_type`` and ``model_class`` enable two
+extremely important use cases:
+
+    1. Using these methods, you can write high-level generic code that
+       performs queries on any installed model -- instead of importing and
+       using a single specific model class, you can pass an ``app_label``
+       and ``model`` into a ``ContentType`` lookup at runtime, and then
+       work with the model class or retrieve objects from it.
+
+    2. You can relate another model to ``ContentType`` as a way of tying
+       instances of it to particular model classes, and use these methods
+       to get access to those model classes.
+
+Several of Django's bundled applications make use of the latter
+technique. For example, `the permissions system`_ in Django's
+authentication framework uses a ``Permission`` model with a foreign
+key to ``ContentType``; this lets ``Permission`` represent concepts
+like "can add blog entry" or "can delete news story".
+
+.. _lookup arguments: ../db-api/#field-lookups
+.. _a get() lookup: ../db-api/#get-kwargs
+.. _the permissions system: ../authentication/#permissions
+
+The ``ContentTypeManager``
+--------------------------
+
+``ContentType`` also has a custom manager, ``ContentTypeManager``,
+which adds the following methods:
+
+    ``clear_cache()``
+        Clears an internal cache used by ``ContentType`` to keep track of which
+        models for which it has created ``ContentType`` instances. You probably
+        won't ever need to call this method yourself; Django will call it
+        automatically when it's needed.
+
+    ``get_for_model(model)``
+        Takes either a model class or an instance of a model, and returns the
+        ``ContentType`` instance representing that model.
+
+The ``get_for_model`` method is especially useful when you know you
+need to work with a ``ContentType`` but don't want to go to the
+trouble of obtaining the model's metadata to perform a manual lookup::
+
+    >>> from django.contrib.auth.models import User
+    >>> user_type = ContentType.objects.get_for_model(User)
+    >>> user_type
+    <ContentType: user>
+
+Generic relations
+=================
+
+Adding a foreign key from one of your own models to ``ContentType``
+allows your model to effectively tie itself to another model class, as
+in the example of the ``Permission`` model above. But it's possible to
+go one step further and use ``ContentType`` to enable truly generic
+(sometimes called "polymorphic") relationships between models.
+
+A simple example is a tagging system, which might look like this::
+
+    from django.db import models
+    from django.contrib.contenttypes.models import ContentType
+    from django.contrib.contenttypes import generic
+
+    class TaggedItem(models.Model):
+        tag = models.SlugField()
+        content_type = models.ForeignKey(ContentType)
+        object_id = models.PositiveIntegerField()
+        content_object = generic.GenericForeignKey('content_type', 'object_id')
+
+        def __unicode__(self):
+            return self.tag
+
+A normal ``ForeignKey`` can only "point to" one other model, which
+means that if the ``TaggedItem`` model used a ``ForeignKey`` it would have to
+choose one and only one model to store tags for. The contenttypes
+application provides a special field type --
+``django.contrib.contenttypes.generic.GenericForeignKey`` -- which
+works around this and allows the relationship to be with any
+model. There are three parts to setting up a ``GenericForeignKey``:
+
+    1. Give your model a ``ForeignKey`` to ``ContentType``.
+
+    2. Give your model a field that can store a primary-key value from the
+       models you'll be relating to. (For most models, this means an
+       ``IntegerField`` or ``PositiveIntegerField``.)
+
+    3. Give your model a ``GenericForeignKey``, and pass it the names of
+       the two fields described above. If these fields are named
+       "content_type" and "object_id", you can omit this -- those are the
+       default field names ``GenericForeignKey`` will look for.
+
+This will enable an API similar to the one used for a normal ``ForeignKey``;
+each ``TaggedItem`` will have a ``content_object`` field that returns the
+object it's related to, and you can also assign to that field or use it when
+creating a ``TaggedItem``::
+
+    >>> from django.contrib.models.auth import User
+    >>> guido = User.objects.get(username='Guido')
+    >>> t = TaggedItem(content_object=guido, tag='bdfl')
+    >>> t.save()
+    >>> t.content_object
+    <User: Guido>
+
+Reverse generic relations
+-------------------------
+
+If you know which models you'll be using most often, you can also add
+a "reverse" generic relationship to enable an additional API. For example::
+
+    class Bookmark(models.Model):
+        url = models.URLField()
+        tags = generic.GenericRelation(TaggedItem)
+
+``Bookmark`` instances will each have a ``tags`` attribute, which can
+be used to retrieve their associated ``TaggedItems``::
+
+    >>> b = Bookmark('http://www.djangoproject.com/')
+    >>> b.save()
+    >>> t1 = TaggedItem(content_object=b, tag='django')
+    >>> t1.save()
+    >>> t2 = TaggedItem(content_object=b, tag='python')
+    >>> t2.save()
+    >>> b.tags.all()
+    [<TaggedItem: django>, <TaggedItem: python>]
+
+If you don't add the reverse relationship, you can do the lookup manually::
+
+    >>> b = Bookmark.objects.get(url='http://www.djangoproject.com/)
+    >>> bookmark_type = ContentType.objects.get_for_model(b)
+    >>> TaggedItem.objects.filter(content_type__pk=bookmark_type.id,
+    ...                           object_id=b.id)
+    [<TaggedItem: django>, <TaggedItem: python>]
+
+Note that if you delete an object that has a ``GenericRelation``, any objects
+which have a ``GenericForeignKey`` pointing at it will be deleted as well. In
+the example above, this means that if a ``Bookmark`` object were deleted, any
+``TaggedItem`` objects pointing at it would be deleted at the same time.