From 145e0a14f0c098d7bbf2bfb593f7b6cfe1b02d72 Mon Sep 17 00:00:00 2001 From: Justin Michalicek Date: Fri, 2 Aug 2013 14:24:26 -0400 Subject: [PATCH] [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 61ecb5f48a from master. --- docs/topics/auth/default.txt | 101 +++++++++++++++++++++++++++++++---- 1 file changed, 92 insertions(+), 9 deletions(-) diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index 657e25a5379..a104a5c9662 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -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 ` 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 + ` 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 + ` 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'] `. 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 + ` 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 ` 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 + ` 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 + ` 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 + ` 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 + ` 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 + ` 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 + ` 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 + ` 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 ----------------