diff --git a/docs/authentication.txt b/docs/authentication.txt index f0259b1cd75..eadf702e884 100644 --- a/docs/authentication.txt +++ b/docs/authentication.txt @@ -154,10 +154,13 @@ custom methods: * ``get_profile()`` -- Returns a site-specific profile for this user. Raises ``django.contrib.auth.models.SiteProfileNotAvailable`` if the current site - doesn't allow profiles. + doesn't allow profiles. For information on how to define a + site-specific user profile, see the section on `storing additional + user information`_ below. .. _Django model: ../model-api/ .. _DEFAULT_FROM_EMAIL: ../settings/#default-from-email +.. _storing additional user information: #storing-additional-information-about-users Manager functions ~~~~~~~~~~~~~~~~~ @@ -269,6 +272,45 @@ you need to create a superuser after that via the command line, you can use the Make sure to substitute ``/path/to/`` with the path to the Django codebase on your filesystem. +Storing additional information about users +------------------------------------------ + +If you'd like to store additional information related to your users, +Django provides a method to specify a site-specific related model -- +termed a "user profile" -- for this purpose. + +To make use of this feature, define a model with fields for the +additional information you'd like to store, or additional methods +you'd like to have available, and also add a ``ForeignKey`` from your +model to the ``User`` model, specified with ``unique=True`` to ensure +only one instance of your model can be created for each ``User``. + +To indicate that this model is the user profile model for a given +site, fill in the setting ``AUTH_PROFILE_MODULE`` with a string +consisting of the following items, separated by a dot: + +1. The (normalized to lower-case) name of the application in which the + user profile model is defined (in other words, an all-lowercase + version of the name which was passed to ``manage.py startapp`` to + create the application). + +2. The (normalized to lower-case) name of the model class. + +For example, if the profile model was a class named ``UserProfile`` +and was defined inside an application named ``accounts``, the +appropriate setting would be:: + + AUTH_PROFILE_MODULE = 'accounts.userprofile' + +When a user profile model has been defined and specified in this +manner, each ``User`` object will have a method -- ``get_profile()`` +-- which returns the instance of the user profile model associated +with that ``User``. + +For more information, see `Chapter 12 of the Django book`_. + +.. _Chapter 12 of the Django book: http://www.djangobook.com/en/beta/chapter12/#cn226 + Authentication in Web requests ============================== diff --git a/docs/settings.txt b/docs/settings.txt index bb055160a5f..79de2ad22f9 100644 --- a/docs/settings.txt +++ b/docs/settings.txt @@ -236,6 +236,16 @@ documentation`_ for details. .. _authentication backends documentation: ../authentication/#other-authentication-sources +AUTH_PROFILE_MODULE +------------------- + +Default: Not defined + +The site-specific user profile model used by this site. See the +`documentation on user profile models`_ for details. + +.. _documentation on user profile models: ../authentication/#storing-additional-information-about-users + CACHE_BACKEND -------------