Ticket #834: 834.diff

File 834.diff, 5.1 KB (added by ubernostrum, 9 years ago)

Documentation for all views and manipulators in the auth app

  • docs/authentication.txt

     
    317317        else:
    318318            # Return an 'invalid login' error message.
    319319
     320Manually checking a user's password
     321-----------------------------------
     322
     323If you'd like to manually authenticate a user by comparing a
     324plain-text password to the hashed password in the database, use the
     325convenience function `django.contrib.auth.models.check_password`. It
     326takes two arguments: the plain-text password to check, and the full
     327value of a user's ``password`` field in the database to check against,
     328and returns ``True`` if they match, ``False`` otherwise.
     329
    320330How to log a user out
    321331---------------------
    322332
     
    444454.. _forms documentation: ../forms/
    445455.. _site framework docs: ../sites/
    446456
     457Other built-in views
     458--------------------
     459
     460In addition to the `login` view, the authentication system includes a
     461few other useful built-in views:
     462
     463``django.contrib.auth.views.logout``
     464~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     465
     466**Description:**
     467
     468Logs a user out.
     469
     470**Optional arguments:**
     471
     472    * ``template_name``: The full name of a template to display after
     473      logging the user out. This will default to
     474      ``registration/logged_out.html`` if no argument is supplied.
     475
     476**Template context:**
     477
     478    * ``title``: The string "Logged out", localized.
     479
     480``django.contrib.auth.views.logout_then_login``
     481~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     482
     483**Description:**
     484
     485Logs a user out, then redirects to the login page.
     486
     487**Optional arguments:**
     488
     489    * ``login_url``: The URL of the login page to redirect to. This
     490      will default to ``/accounts/login/`` if not supplied.
     491
     492``django.contrib.auth.views.password_change``
     493~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     494
     495**Description:**
     496
     497Allows a user to change their password.
     498
     499**Optional arguments:**
     500
     501    * ``template_name``: The full name of a template to use for
     502      displaying the password change form. This will default to
     503      ``registration/password_change_form.html`` if not supplied.
     504
     505**Template context:**
     506
     507    * ``form``: The password change form.
     508
     509``django.contrib.auth.views.password_change_done``
     510~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     511
     512**Description:**
     513
     514The page shown after a user has changed their password.
     515
     516**Optional arguments:**
     517
     518    * ``template_name``: The full name of a template to use. This will
     519      default to ``registration/password_change_done.html`` if not
     520      supplied.
     521
     522``django.contrib.auth.views.password_reset``
     523~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     524
     525**Description:**
     526
     527Allows a user to reset their password, and sends them the new password
     528in an email.
     529
     530**Optional arguments:**
     531
     532    * ``template_name``: The full name of a template to use for
     533      displaying the password reset form. This will default to
     534      ``registration/password_reset_form.html`` if not supplied.
     535
     536    * ``email_template_name``: The full name of a template to use for
     537      generating the email with the new password. This will default to
     538      ``registration/password_reset_email.html`` if not supplied.
     539
     540**Template context:**
     541
     542    * ``form``: The form for resetting the user's password.
     543
     544``django.contrib.auth.views.password_reset_done``
     545~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     546
     547**Description:**
     548
     549The page shown after a user has reset their password.
     550
     551**Optional arguments:**
     552
     553    * ``template_name``: The full name of a template to use. This will
     554      default to ``registration/password_reset_done.html`` if not
     555      supplied.
     556
     557``django.contrib.auth.views.redirect_to_login``
     558~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
     559
     560**Description:**
     561
     562Redirects to the login page, and then back to another URL after a
     563successful login.
     564
     565**Required arguments:**
     566
     567    * ``next``: The URL to redirect to after a successful login.
     568
     569**Optional arguments:**
     570
     571    * ``login_url``: The URL of the login page to redirect to. This
     572      will default to ``/accounts/login/`` if not supplied.
     573
     574Built-in manipulators
     575---------------------
     576
     577If you don't want to use the built-in views, but want the convenience
     578of not having to write manipulators for this functionality, the
     579authentication system provides several built-in manipulators:
     580
     581    * ``django.contrib.auth.forms.AdminPasswordChangeForm``: A
     582      manipulator used in the admin interface to change a user's
     583      password.
     584
     585    * ``django.contrib.auth.forms.AuthenticationForm``: A manipulator
     586      for logging a user in.
     587
     588    * ``django.contrib.auth.forms.PasswordChangeForm``: A manipulator
     589      for allowing a user to change their password.
     590
     591    * ``django.contrib.auth.forms.PasswordResetForm``: A manipulator
     592      for resetting a user's password and emailing the new password to
     593      them.
     594
     595    * ``django.contrib.auth.forms.UserCreationForm``: A manipulator
     596      for creating a new user.
     597
    447598Limiting access to logged-in users that pass a test
    448599---------------------------------------------------
Back to Top