Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

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
authored November 07, 2010

Showing 1 changed file with 24 additions and 21 deletions. Show diff stats Hide diff stats

  1. 45  docs/topics/auth.txt
45  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, login_url=None])
697 697
 
698 698
     As a shortcut, you can use the convenient
699 699
     :func:`~django.contrib.auth.decorators.login_required` decorator::
@@ -703,17 +703,33 @@ 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:
706 708
 
707  
-    :func:`~django.contrib.auth.decorators.login_required` also takes an
708  
-    optional ``redirect_field_name`` parameter. Example::
  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/``.
709 712
 
  713
+    * If the user is logged in, execute the view normally. The view code is
  714
+      free to assume the user is logged in.
  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
 
  728
+    Note that 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).
  732
+
717 733
     .. versionadded:: 1.3
718 734
 
719 735
     :func:`~django.contrib.auth.decorators.login_required` also takes an
@@ -725,24 +741,11 @@ The login_required decorator
725 741
         def my_view(request):
726 742
             ...
727 743
 
728  
-    :func:`~django.contrib.auth.decorators.login_required` does the following:
729  
-
730  
-        * If the user isn't logged in, redirect to
731  
-          :setting:`settings.LOGIN_URL <LOGIN_URL>` (``/accounts/login/`` by
732  
-          default), passing the current absolute URL in the query string. The
733  
-          name of the GET argument is determined by the ``redirect_field_name``
734  
-          argument provided to the decorator. The default argument name is
735  
-          ``next``. For example:
736  
-          ``/accounts/login/?next=/polls/3/``.
737  
-
738  
-        * If the user is logged in, execute the view normally. The view code is
739  
-          free to assume the user is logged in.
740  
-
741  
-Note that if you don't specify the ``login_url`` parameter, you'll need to map
742  
-the appropriate Django view to :setting:`settings.LOGIN_URL <LOGIN_URL>`. For
743  
-example, using the defaults, add the following line to your URLconf::
  744
+    Note that if you don't specify the ``login_url`` parameter, you'll need to map
  745
+    the appropriate Django view to :setting:`settings.LOGIN_URL <LOGIN_URL>`. For
  746
+    example, using the defaults, add the following line to your URLconf::
744 747
 
745  
-    (r'^accounts/login/$', 'django.contrib.auth.views.login'),
  748
+        (r'^accounts/login/$', 'django.contrib.auth.views.login'),
746 749
 
747 750
 .. function:: views.login(request, [template_name, redirect_field_name, authentication_form])
748 751
 

0 notes on commit 1a878f3

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