From 1a878f30b0910bce4049643740bea2c693f9a1a0 Mon Sep 17 00:00:00 2001 From: Gabriel Hurley Date: Sun, 7 Nov 2010 00:56:59 +0000 Subject: [PATCH] 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 --- docs/topics/auth.txt | 45 +++++++++++++++++++++++--------------------- 1 file changed, 24 insertions(+), 21 deletions(-) diff --git a/docs/topics/auth.txt b/docs/topics/auth.txt index 4093d9f583..f45c61a94b 100644 --- a/docs/topics/auth.txt +++ b/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 `, 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 `. 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 ` (``/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 `. 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])