Commit 145e0a14 authored by Justin Michalicek's avatar Justin Michalicek Committed by Tim Graham
Browse files

[1.5.x] Fixed #20855 -- Added documentation of current_app and extra_context... 

[1.5.x] Fixed #20855 -- Added documentation of current_app and extra_context params to django.contrib.auth views

refs #5298 and refs #8342

Backport of 61ecb5f4 from master.
parent f4806e3e

docs/topics/auth/default.txt

+92 −9
Original line number Diff line number Diff line
@@ -565,13 +565,33 @@ Most built-in authentication views provide a URL name for easier reference. See 
patterns.





.. function:: login(request, [template_name, redirect_field_name, authentication_form])

.. function:: login(request, [template_name, redirect_field_name, authentication_form, current_app, extra_context])



    **URL name:** ``login``



    See :doc:`the URL documentation </topics/http/urls>` for details on using

    named URL patterns.



    **Optional arguments:**



    * ``template_name``: The name of a template to display for the view used to

      log the user in. Defaults to :file:`registration/login.html`.



    * ``redirect_field_name``: The name of a ``GET`` field containing the

      URL to redirect to after login. Overrides ``next`` if the given

      ``GET`` parameter is passed.



    * ``authentication_form``: A callable (typically just a form class) to

      use for authentication. Defaults to

      :class:`~django.contrib.auth.forms.AuthenticationForm`.



    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



    Here's what ``django.contrib.auth.views.login`` does:



    * If called via ``GET``, it displays a login form that POSTs to the
@@ -661,7 +681,7 @@ patterns. 
    .. _site framework docs: ../sites/





.. function:: logout(request, [next_page, template_name, redirect_field_name])

.. function:: logout(request, [next_page, template_name, redirect_field_name, current_app, extra_context])



    Logs a user out.
@@ -679,6 +699,13 @@ patterns. 
      URL to redirect to after log out. Overrides ``next_page`` if the given

      ``GET`` parameter is passed.



    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



    **Template context:**



    * ``title``: The string "Logged out", localized.
@@ -695,7 +722,14 @@ patterns. 
      :attr:`request.META['SERVER_NAME'] <django.http.HttpRequest.META>`.

      For more on sites, see :doc:`/ref/contrib/sites`.



.. function:: logout_then_login(request[, login_url])

    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



.. function:: logout_then_login(request[, login_url, current_app, extra_context])



    Logs a user out, then redirects to the login page.
@@ -706,7 +740,14 @@ patterns. 
    * ``login_url``: The URL of the login page to redirect to.

      Defaults to :setting:`settings.LOGIN_URL <LOGIN_URL>` if not supplied.



.. function:: password_change(request[, template_name, post_change_redirect, password_change_form])

    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



.. function:: password_change(request[, template_name, post_change_redirect, password_change_form, current_app, extra_context])



    Allows a user to change their password.
@@ -726,11 +767,18 @@ patterns. 
      actually changing the user's password. Defaults to

      :class:`~django.contrib.auth.forms.PasswordChangeForm`.



    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



    **Template context:**



    * ``form``: The password change form (see ``password_change_form`` above).



.. function:: password_change_done(request[, template_name])

.. function:: password_change_done(request[, template_name, current_app, extra_context])



    The page shown after a user has changed their password.
@@ -742,7 +790,14 @@ patterns. 
      Defaults to :file:`registration/password_change_done.html` if not

      supplied.



.. function:: password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email])

    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



.. function:: password_reset(request[, is_admin_site, template_name, email_template_name, password_reset_form, token_generator, post_reset_redirect, from_email, current_app, extra_context])



    Allows a user to reset their password by generating a one-time use link

    that can be used to reset the password, and sending that link to the
@@ -786,6 +841,13 @@ patterns. 
    * ``from_email``: A valid email address. By default Django uses

      the :setting:`DEFAULT_FROM_EMAIL`.



    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



    **Template context:**



    * ``form``: The form (see ``password_reset_form`` above) for resetting
@@ -825,7 +887,7 @@ patterns. 
    single line plain text string.





.. function:: password_reset_done(request[, template_name])

.. function:: password_reset_done(request[, template_name, current_app, extra_context])



    The page shown after a user has been emailed a link to reset their

    password. This view is called by default if the :func:`password_reset` view
@@ -839,7 +901,14 @@ patterns. 
      Defaults to :file:`registration/password_reset_done.html` if not

      supplied.



.. function:: password_reset_confirm(request[, uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect])

    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



.. function:: password_reset_confirm(request[, uidb36, token, template_name, token_generator, set_password_form, post_reset_redirect, current_app, extra_context])



    Presents a form for entering a new password.
@@ -865,6 +934,13 @@ patterns. 
    * ``post_reset_redirect``: URL to redirect after the password reset

      done. Defaults to ``None``.



    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



    **Template context:**



    * ``form``: The form (see ``set_password_form`` above) for setting the
@@ -873,7 +949,7 @@ patterns. 
    * ``validlink``: Boolean, True if the link (combination of uidb36 and

      token) is valid or unused yet.



.. function:: password_reset_complete(request[,template_name])

.. function:: password_reset_complete(request[,template_name, current_app, extra_context])



   Presents a view which informs the user that the password has been

   successfully changed.
@@ -885,6 +961,13 @@ patterns. 
   * ``template_name``: The full name of a template to display the view.

     Defaults to :file:`registration/password_reset_complete.html`.



    * ``current_app``: A hint indicating which application contains the current

      view. See the :ref:`namespaced URL resolution strategy

      <topics-http-reversing-url-namespaces>` for more information.



    * ``extra_context``: A dictionary of context data that will be added to the

      default context data passed to the template.



Helper functions

----------------