The ContactForm class

class contact_form.forms.ContactForm

The base contact form class from which all contact form classes should inherit.

If you don’t need any custom functionality, you can simply use this form to provide basic contact functionality; it will collect name, email address and message.

The ContactFormView included in this application knows how to work with this form and can handle many types of subclasses as well (see below for a discussion of the important points), so in many cases it will be all that you need. If you’d like to use this form or a subclass of it from one of your own views, just do the following:

  1. When you instantiate the form, pass the current HttpRequest object to the constructor as the keyword argument request; this is used internally by the base implementation, and also made available so that subclasses can add functionality which relies on inspecting the request (such as spam filtering).
  2. To send the message, call the form’s save method, which accepts the keyword argument fail_silently and defaults it to False. This argument is passed directly to send_mail, and allows you to suppress or raise exceptions as needed for debugging. The save method has no return value.

Other than that, treat it like any other form; validity checks and validated data are handled normally, through the is_valid method and the cleaned_data dictionary.

Under the hood, this form uses a somewhat abstracted interface in order to make it easier to subclass and add functionality.

These attributes play a role in determining behavior:

from_email

The email address to use in the From: header of the message. This can also be implemented as a method named from_email(), in which case it will be called when constructing the message. By default, this is the value of the setting DEFAULT_FROM_EMAIL.

recipient_list

The list of recipients for the message. This can also be implemented as a method named recipient_list(), in which case it will be called when constructing the message. By default, this is the email addresses specified in the setting MANAGERS.

subject_template_name

The name of the template to use when rendering the subject line of the message. By default, this is contact_form/contact_form_subject.txt.

template_name

The name of the template to use when rendering the body of the message. By default, this is contact_form/contact_form.txt.

And two methods are involved in actually producing the contents of the message to send:

message()

Returns the body of the message to send. By default, this is accomplished by rendering the template name specified in template_name.

subject()

Returns the subject line of the message to send. By default, this is accomplished by rendering the template name specified in subject_template_name.

Finally, the message itself is generated by the following two methods:

get_message_dict()

This method loops through from_email, recipient_list, message() and subject(), collecting those parts into a dictionary with keys corresponding to the arguments to Django’s send_mail function, then returns the dictionary. Overriding this allows essentially unlimited customization of how the message is generated.

get_context()

For methods which render portions of the message using templates (by default, message() and subject()), generates the context used by those templates. The default context will be a RequestContext (using the current HTTP request, so user information is available), plus the contents of the form’s cleaned_data dictionary, and one additional variable:

site
If django.contrib.sites is installed, the currently-active Site object. Otherwise, a RequestSite object generated from the request.

Meanwhile, the following attributes/methods generally should not be overridden; doing so may interfere with functionality, may not accomplish what you want, and generally any desired customization can be accomplished in a more straightforward way through overriding one of the attributes/methods listed above.

request

The HttpRequest object representing the current request. This is set automatically in __init__(), and is used both to generate a RequestContext for the templates and to allow subclasses to engage in request-specific behavior.

save()

If the form has data and is valid, will actually send the email, by calling get_message_dict() and passing the result to Django’s send_mail function.

Note that subclasses which override __init__ or save() need to accept *args and **kwargs, and pass them via super, in order to preserve behavior (each of those methods accepts at least one additional argument, and this application expects and requires them to do so).