diff --git a/docs/topics/auth/default.txt b/docs/topics/auth/default.txt index 6cdda816a6..554e58b838 100644 --- a/docs/topics/auth/default.txt +++ b/docs/topics/auth/default.txt @@ -680,18 +680,78 @@ Django provides several views that you can use for handling login, logout, and password management. These make use of the :ref:`stock auth forms ` but you can pass in your own forms as well. -Django provides no default template for the authentication views - however the -template context is documented for each view below. +Django provides no default template for the authentication views. You should +create your own templates for the views you want to use. The template context +is documented in each view, see :ref:`all-authentication-views`. -The built-in views all return -a :class:`~django.template.response.TemplateResponse` instance, which allows -you to easily customize the response data before rendering. For more details, -see the :doc:`TemplateResponse documentation `. +.. _using-the-views: -Most built-in authentication views provide a URL name for easier reference. See -:doc:`the URL documentation ` for details on using named URL -patterns. +Using the views +~~~~~~~~~~~~~~~ +There are different methods to implement these views in your project. The +easiest way is to include the provided URLconf in ``django.contrib.auth.urls`` +in your own URLconf, for example:: + + urlpatterns = [ + url('^', include('django.contrib.auth.urls')) + ] + +This will include the following URL patterns:: + + ^login/$ [name='login'] + ^logout/$ [name='logout'] + ^password_change/$ [name='password_change'] + ^password_change/done/$ [name='password_change_done'] + ^password_reset/$ [name='password_reset'] + ^password_reset/done/$ [name='password_reset_done'] + ^reset/(?P[0-9A-Za-z_\-]+)/(?P[0-9A-Za-z]{1,13}-[0-9A-Za-z]{1,20})/$ [name='password_reset_confirm'] + ^reset/done/$ [name='password_reset_complete'] + +The views provide a URL name for easier reference. See :doc:`the URL +documentation ` for details on using named URL patterns. + +If you want more control over your URLs, you can reference a specific view in +your URLconf:: + + urlpatterns = [ + url('^change-password/', 'django.contrib.auth.views.password_change') + ] + +The views have optional arguments you can use to alter the behavior of the +view. For example, if you want to change the template name a view uses, you can +provide the ``template_name`` argument. A way to do this is to provide keyword +arguments in the URLconf, these will be passed on to the view. For example:: + + urlpatterns = [ + url( + '^change-password/', + 'django.contrib.auth.views.password_change', + {'template_name': 'change-password.html'} + ) + ] + +All views return a :class:`~django.template.response.TemplateResponse` +instance, which allows you to easily customize the response data before +rendering. A way to do this is to wrap a view in your own view:: + + from django.contrib.auth import views + + def change_password(request): + template_response = views.password_change(request) + # Do something with `template_response` + return template_response + +For more details, see the :doc:`TemplateResponse documentation +`. + +.. _all-authentication-views: + +All authentication views +~~~~~~~~~~~~~~~~~~~~~~~~ + +This is a list with all the views ``django.contrib.auth`` provides. For +implementation details see :ref:`using-the-views`. .. function:: login(request, [template_name, redirect_field_name, authentication_form, current_app, extra_context])