Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Browse files

Fixed #8325 -- Reorganization and expansion of the login_required dec…

…orator 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
  • Loading branch information...
commit 1a878f30b0910bce4049643740bea2c693f9a1a0 1 parent 11b0120
Gabriel Hurley authored
Showing with 24 additions and 21 deletions.
  1. +24 −21 docs/topics/auth.txt
View
45 docs/topics/auth.txt
@@ -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:
-
- * 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::
+ 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])
Please sign in to comment.
Something went wrong with that request. Please try again.