Code

Ticket #834: 834.diff

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

Documentation for all views and manipulators in the auth app

Line 
1Index: docs/authentication.txt
2===================================================================
3--- docs/authentication.txt     (revision 4613)
4+++ docs/authentication.txt     (working copy)
5@@ -317,6 +317,16 @@
6         else:
7             # Return an 'invalid login' error message.
8 
9+Manually checking a user's password
10+-----------------------------------
11+
12+If you'd like to manually authenticate a user by comparing a
13+plain-text password to the hashed password in the database, use the
14+convenience function `django.contrib.auth.models.check_password`. It
15+takes two arguments: the plain-text password to check, and the full
16+value of a user's ``password`` field in the database to check against,
17+and returns ``True`` if they match, ``False`` otherwise.
18+
19 How to log a user out
20 ---------------------
21 
22@@ -444,6 +454,147 @@
23 .. _forms documentation: ../forms/
24 .. _site framework docs: ../sites/
25 
26+Other built-in views
27+--------------------
28+
29+In addition to the `login` view, the authentication system includes a
30+few other useful built-in views:
31+
32+``django.contrib.auth.views.logout``
33+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
34+
35+**Description:**
36+
37+Logs a user out.
38+
39+**Optional arguments:**
40+
41+    * ``template_name``: The full name of a template to display after
42+      logging the user out. This will default to
43+      ``registration/logged_out.html`` if no argument is supplied.
44+
45+**Template context:**
46+
47+    * ``title``: The string "Logged out", localized.
48+
49+``django.contrib.auth.views.logout_then_login``
50+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
51+
52+**Description:**
53+
54+Logs a user out, then redirects to the login page.
55+
56+**Optional arguments:**
57+
58+    * ``login_url``: The URL of the login page to redirect to. This
59+      will default to ``/accounts/login/`` if not supplied.
60+
61+``django.contrib.auth.views.password_change``
62+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
63+
64+**Description:**
65+
66+Allows a user to change their password.
67+
68+**Optional arguments:**
69+
70+    * ``template_name``: The full name of a template to use for
71+      displaying the password change form. This will default to
72+      ``registration/password_change_form.html`` if not supplied.
73+
74+**Template context:**
75+
76+    * ``form``: The password change form.
77+
78+``django.contrib.auth.views.password_change_done``
79+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
80+
81+**Description:**
82+
83+The page shown after a user has changed their password.
84+
85+**Optional arguments:**
86+
87+    * ``template_name``: The full name of a template to use. This will
88+      default to ``registration/password_change_done.html`` if not
89+      supplied.
90+
91+``django.contrib.auth.views.password_reset``
92+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
93+
94+**Description:**
95+
96+Allows a user to reset their password, and sends them the new password
97+in an email.
98+
99+**Optional arguments:**
100+
101+    * ``template_name``: The full name of a template to use for
102+      displaying the password reset form. This will default to
103+      ``registration/password_reset_form.html`` if not supplied.
104+
105+    * ``email_template_name``: The full name of a template to use for
106+      generating the email with the new password. This will default to
107+      ``registration/password_reset_email.html`` if not supplied.
108+
109+**Template context:**
110+
111+    * ``form``: The form for resetting the user's password.
112+
113+``django.contrib.auth.views.password_reset_done``
114+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
115+
116+**Description:**
117+
118+The page shown after a user has reset their password.
119+
120+**Optional arguments:**
121+
122+    * ``template_name``: The full name of a template to use. This will
123+      default to ``registration/password_reset_done.html`` if not
124+      supplied.
125+
126+``django.contrib.auth.views.redirect_to_login``
127+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
128+
129+**Description:**
130+
131+Redirects to the login page, and then back to another URL after a
132+successful login.
133+
134+**Required arguments:**
135+
136+    * ``next``: The URL to redirect to after a successful login.
137+
138+**Optional arguments:**
139+
140+    * ``login_url``: The URL of the login page to redirect to. This
141+      will default to ``/accounts/login/`` if not supplied.
142+
143+Built-in manipulators
144+---------------------
145+
146+If you don't want to use the built-in views, but want the convenience
147+of not having to write manipulators for this functionality, the
148+authentication system provides several built-in manipulators:
149+
150+    * ``django.contrib.auth.forms.AdminPasswordChangeForm``: A
151+      manipulator used in the admin interface to change a user's
152+      password.
153+
154+    * ``django.contrib.auth.forms.AuthenticationForm``: A manipulator
155+      for logging a user in.
156+
157+    * ``django.contrib.auth.forms.PasswordChangeForm``: A manipulator
158+      for allowing a user to change their password.
159+
160+    * ``django.contrib.auth.forms.PasswordResetForm``: A manipulator
161+      for resetting a user's password and emailing the new password to
162+      them.
163+
164+    * ``django.contrib.auth.forms.UserCreationForm``: A manipulator
165+      for creating a new user.
166+
167 Limiting access to logged-in users that pass a test
168 ---------------------------------------------------