X-Git-Url: http://git.ithinksw.org/philo.git/blobdiff_plain/943e8bc4af0c11b0ace3811199e3b0844c4c3fbc..a7d3a2c29add2278e4e9aa3fd8e5ff847a3c9a87:/philo/contrib/waldo/forms.py

diff --git a/philo/contrib/waldo/forms.py b/philo/contrib/waldo/forms.py
index 4cc9874..8e14ba5 100644
--- a/philo/contrib/waldo/forms.py
+++ b/philo/contrib/waldo/forms.py
@@ -12,10 +12,18 @@ from philo.contrib.waldo.tokens import REGISTRATION_TIMEOUT_DAYS
 
 
 class EmailInput(forms.TextInput):
+	"""Displays an HTML5 email input on browsers which support it and a normal text input on other browsers."""
 	input_type = 'email'
 
 
 class RegistrationForm(UserCreationForm):
+	"""
+	Handles user registration. If :mod:`recaptcha_django` is installed on the system and :class:`recaptcha_django.middleware.ReCaptchaMiddleware` is in :setting:`settings.MIDDLEWARE_CLASSES`, then a recaptcha field will automatically be added to the registration form.
+	
+	.. seealso:: `recaptcha-django <http://code.google.com/p/recaptcha-django/>`_
+	
+	"""
+	#: An :class:`EmailField` using the :class:`EmailInput` widget.
 	email = forms.EmailField(widget=EmailInput)
 	try:
 		from recaptcha_django import ReCaptchaField
@@ -57,6 +65,7 @@ class RegistrationForm(UserCreationForm):
 
 
 class UserAccountForm(forms.ModelForm):
+	"""Handles a user's account - by default, :attr:`auth.User.first_name`, :attr:`auth.User.last_name`, :attr:`auth.User.email`."""
 	first_name = User._meta.get_field('first_name').formfield(required=True)
 	last_name = User._meta.get_field('last_name').formfield(required=True)
 	email = User._meta.get_field('email').formfield(required=True, widget=EmailInput)
@@ -65,12 +74,37 @@ class UserAccountForm(forms.ModelForm):
 		kwargs['instance'] = user
 		super(UserAccountForm, self).__init__(*args, **kwargs)
 	
+	def email_changed(self):
+		"""Returns ``True`` if the email field changed value and ``False`` if it did not, or if there is no email field on the form. This method must be supplied by account forms used with :mod:`~philo.contrib.waldo`."""
+		return 'email' in self.changed_data
+	
+	def reset_email(self):
+		"""
+		ModelForms modify their instances in-place during :meth:`_post_clean`; this method resets the email value to its initial state and returns the altered value. This is a method on the form to allow unusual behavior such as storing email on a :class:`UserProfile`.
+		
+		"""
+		email = self.instance.email
+		self.instance.email = self.initial['email']
+		self.cleaned_data.pop('email')
+		return email
+	
+	@classmethod
+	def set_email(cls, user, email):
+		"""
+		Given a valid instance and an email address, correctly set the email address for that instance and save the changes. This is a class method in order to allow unusual behavior such as storing email on a :class:`UserProfile`.
+		
+		"""
+		user.email = email
+		user.save()
+		
+	
 	class Meta:
 		model = User
 		fields = ('first_name', 'last_name', 'email')
 
 
 class WaldoAuthenticationForm(AuthenticationForm):
+	"""Handles user authentication. Checks that the user has not mistakenly entered their email address (like :class:`django.contrib.admin.forms.AdminAuthenticationForm`) but does not require that the user be staff."""
 	ERROR_MESSAGE = _("Please enter a correct username and password. Note that both fields are case-sensitive.")
 	
 	def clean(self):
@@ -94,11 +128,4 @@ class WaldoAuthenticationForm(AuthenticationForm):
 			elif not self.user_cache.is_active:
 				raise ValidationError(message)
 		self.check_for_test_cookie()
-		return self.cleaned_data
-	
-	def check_for_test_cookie(self):
-		# This method duplicates the Django 1.3 AuthenticationForm method.
-		if self.request and not self.request.session.test_cookie_worked():
-			raise forms.ValidationError(
-				_("Your Web browser doesn't appear to have cookies enabled. "
-				  "Cookies are required for logging in."))
\ No newline at end of file
+		return self.cleaned_data
\ No newline at end of file