Fixed #8325 -- Reorganization and expansion of the login_required decorator docs to make it clearer how the redirect_field_name parameter works and improve the overall flow of the text. Thanks to Robert Reeves for the report.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@14480 bcc190cf-cafb-0310-a4f2-bffc1f526a37
This commit is contained in:
Gabriel Hurley 2010-11-07 00:56:59 +00:00
parent 11b012038c
commit 1a878f30b0
1 changed files with 24 additions and 21 deletions

View File

@ -693,7 +693,7 @@ login page::
The login_required decorator
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. function:: decorators.login_required()
.. function:: decorators.login_required([redirect_field_name=REDIRECT_FIELD_NAME, login_url=None])
As a shortcut, you can use the convenient
:func:`~django.contrib.auth.decorators.login_required` decorator::
@ -703,17 +703,33 @@ The login_required decorator
@login_required
def my_view(request):
...
:func:`~django.contrib.auth.decorators.login_required` does the following:
:func:`~django.contrib.auth.decorators.login_required` also takes an
optional ``redirect_field_name`` parameter. Example::
* If the user isn't logged in, redirect to
:setting:`settings.LOGIN_URL <LOGIN_URL>`, passing the current absolute
path in the query string. Example: ``/accounts/login/?next=/polls/3/``.
* If the user is logged in, execute the view normally. The view code is
free to assume the user is logged in.
By default, the path that the user should be redirected to upon
successful authentication is stored in a query string parameter called
``"next"``. If you would prefer to use a different name for this parameter,
:func:`~django.contrib.auth.decorators.login_required` takes an
optional ``redirect_field_name`` parameter::
from django.contrib.auth.decorators import login_required
@login_required(redirect_field_name='redirect_to')
@login_required(redirect_field_name='my_redirect_field')
def my_view(request):
...
Note that if you provide a value to ``redirect_field_name``, you will most
likely need to customize your login template as well, since the template
context variable which stores the redirect path will use the value of
``redirect_field_name`` as it's key rather than ``"next"`` (the default).
.. versionadded:: 1.3
:func:`~django.contrib.auth.decorators.login_required` also takes an
@ -725,24 +741,11 @@ The login_required decorator
def my_view(request):
...
:func:`~django.contrib.auth.decorators.login_required` does the following:
Note that if you don't specify the ``login_url`` parameter, you'll need to map
the appropriate Django view to :setting:`settings.LOGIN_URL <LOGIN_URL>`. For
example, using the defaults, add the following line to your URLconf::
* If the user isn't logged in, redirect to
:setting:`settings.LOGIN_URL <LOGIN_URL>` (``/accounts/login/`` by
default), passing the current absolute URL in the query string. The
name of the GET argument is determined by the ``redirect_field_name``
argument provided to the decorator. The default argument name is
``next``. For example:
``/accounts/login/?next=/polls/3/``.
* If the user is logged in, execute the view normally. The view code is
free to assume the user is logged in.
Note that if you don't specify the ``login_url`` parameter, you'll need to map
the appropriate Django view to :setting:`settings.LOGIN_URL <LOGIN_URL>`. For
example, using the defaults, add the following line to your URLconf::
(r'^accounts/login/$', 'django.contrib.auth.views.login'),
(r'^accounts/login/$', 'django.contrib.auth.views.login'),
.. function:: views.login(request, [template_name, redirect_field_name, authentication_form])