Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

[1.2.X] Fixed #8325 -- Reorganization and expansion of the login_requ…

…ired 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.

Backport of [14480] from trunk (sans 1.3-specific changes).

git-svn-id: http://code.djangoproject.com/svn/django/branches/releases/1.2.X@14481 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 2946a657cd339345dd2a6ba56045ba0a37b9995c 1 parent d8e0052
authored November 07, 2010

Showing 1 changed file with 23 additions and 20 deletions. Show diff stats Hide diff stats

  1. 43  docs/topics/auth.txt
43  docs/topics/auth.txt
@@ -693,7 +693,7 @@ login page::
693 693
 The login_required decorator
694 694
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
695 695
 
696  
-.. function:: decorators.login_required()
  696
+.. function:: decorators.login_required([redirect_field_name=REDIRECT_FIELD_NAME])
697 697
 
698 698
     As a shortcut, you can use the convenient
699 699
     :func:`~django.contrib.auth.decorators.login_required` decorator::
@@ -703,35 +703,38 @@ The login_required decorator
703 703
         @login_required
704 704
         def my_view(request):
705 705
             ...
  706
+    
  707
+    :func:`~django.contrib.auth.decorators.login_required` does the following:
  708
+
  709
+    * If the user isn't logged in, redirect to
  710
+      :setting:`settings.LOGIN_URL <LOGIN_URL>`, passing the current absolute
  711
+      path in the query string. Example: ``/accounts/login/?next=/polls/3/``.
706 712
 
707  
-    :func:`~django.contrib.auth.decorators.login_required` also takes an
708  
-    optional ``redirect_field_name`` parameter. Example::
  713
+    * If the user is logged in, execute the view normally. The view code is
  714
+      free to assume the user is logged in.
709 715
 
  716
+    By default, the path that the user should be redirected to upon
  717
+    successful authentication is stored in a query string parameter called
  718
+    ``"next"``. If you would prefer to use a different name for this parameter,
  719
+    :func:`~django.contrib.auth.decorators.login_required` takes an
  720
+    optional ``redirect_field_name`` parameter::
710 721
 
711 722
         from django.contrib.auth.decorators import login_required
712 723
 
713  
-        @login_required(redirect_field_name='redirect_to')
  724
+        @login_required(redirect_field_name='my_redirect_field')
714 725
         def my_view(request):
715 726
             ...
716 727
 
717  
-    :func:`~django.contrib.auth.decorators.login_required` does the following:
718  
-
719  
-        * If the user isn't logged in, redirect to
720  
-          :setting:`settings.LOGIN_URL <LOGIN_URL>` (``/accounts/login/`` by
721  
-          default), passing the current absolute URL in the query string. The
722  
-          name of the GET argument is determined by the ``redirect_field_name``
723  
-          argument provided to the decorator. The default argument name is
724  
-          ``next``. For example:
725  
-          ``/accounts/login/?next=/polls/3/``.
726  
-
727  
-        * If the user is logged in, execute the view normally. The view code is
728  
-          free to assume the user is logged in.
  728
+    If you provide a value to ``redirect_field_name``, you will most
  729
+    likely need to customize your login template as well, since the template
  730
+    context variable which stores the redirect path will use the value of
  731
+    ``redirect_field_name`` as it's key rather than ``"next"`` (the default).
729 732
 
730  
-Note that you'll need to map the appropriate Django view to
731  
-:setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults, add
732  
-the following line to your URLconf::
  733
+    Note that you'll need to map the appropriate Django view to
  734
+    :setting:`settings.LOGIN_URL <LOGIN_URL>`. For example, using the defaults,
  735
+    add the following line to your URLconf::
733 736
 
734  
-    (r'^accounts/login/$', 'django.contrib.auth.views.login'),
  737
+        (r'^accounts/login/$', 'django.contrib.auth.views.login'),
735 738
 
736 739
 .. function:: views.login(request, [template_name, redirect_field_name, authentication_form])
737 740
 

0 notes on commit 2946a65

Please sign in to comment.
Something went wrong with that request. Please try again.