django-contact-form ¶

Installation guide¶

Before installing django-contact-form, you’ll need to have a copy of Django already installed. For information on obtaining and installing Django, consult the Django download page, which offers convenient packaged downloads and installation instructions.

The release of django-contact-form supports Django 1.8, 1.9, and 1.10, on the following Python versions:

• Django 1.8 suports Python 2.7, 3.3, 3.4 and 3.5.
• Django 1.9 supports Python 2.7, 3.4 and 3.5.
• Django 1.10 supports Python 2.7, 3.4 and 3.5.

It is expected that django-contact-form will work without modification on Python 3.6 once it is released.

pip install django-contact-form

python setup.py install

git clone https://github.com/ubernostrum/django-contact-form.git

Quick start guide¶

First you’ll need to have Django and django-contact-form installed; for details on that, see the installation guide.

Once that’s done, you can start setting up django-contact-form. Since it doesn’t provide any database models or use any other application-config mechanisms, you do not need to add django-contact-form to your INSTALLED_APPS setting; you can simply begin using it right away.

URL configuration¶

The easiest way to set up the views in django-contact-form is to just use the provided URLconf, found at contact_form.urls. You can include it wherever you like in your site’s URL configuration; for example, to have it live at the URL /contact/:

from django.conf.urls import include, url


urlpatterns = [
    # ... other URL patterns for your site ...
    url(r'^contact/', include('contact_form.urls')),
]

If you’ll be using a custom form class, you’ll need to manually set up your URLs so you can tell django-contact-form about your form class. For example:

from django.conf.urls import include, url
from django.views.generic import TemplateView

from contact_form.views import ContactFormView

from yourapp.forms import YourCustomFormClass


urlpatterns = [
    # ... other URL patterns for your site ...
    url(r'^contact/$',
        ContactFormView.as_view(
            form_class=YourCustomFormClass),
        name='contact_form'),
    url(r'^contact/sent/$',
        TemplateView.as_view(
            template_name='contact_form/contact_form_sent.html'),
        name='contact_form_sent'),
]

Required templates¶

The two views above will need two templates to be created:

contact_form/contact_form.html

This is used to display the contact form. It has a RequestContext (so any context processors will be applied), and also provides the form instance as the context variable form.

contact_form/contact_form_sent.html

This is used after a successful form submission, to let the user know their message has been sent. It has a RequestContext, but provides no additional context variables of its own.

You’ll also need to create at least two more templates to handle the rendering of the message: contact_form/contact_form_subject.txt for the subject line of the email to send, and contact_form/contact_form.txt for the body (note that the file extension for these is .txt, not .html!). Both of these will receive a RequestContext with a set of variables named for the fields of the form (by default: name, email and body), as well as one more variable: site, representing the current site (either a Site or RequestSite instance, depending on whether Django’s sites framework is installed).

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 customization, 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 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 Django’s send_mail() function, 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.

The following attributes play a role in determining behavior, and any of them can be implemented as an attribute or as a method:

from_email¶

The email address to use in the From: header of the message. By default, this is the value of the setting DEFAULT_FROM_EMAIL.

recipient_list¶

The list of recipients for 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. Note that for compatibility, implementations which override this should support callables for the values of from_email and recipient_list.

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).

Built-in views¶

class contact_form.views.ContactFormView¶

The base view class from which most custom contact-form views should inherit. If you don’t need any custom functionality, and are content with the default ContactForm class, you can also just use it as-is (and the provided URLConf, contact_form.urls, does exactly this).

This is a subclass of Django’s FormView, so refer to the Django documentation for a list of attributes/methods which can be overridden to customize behavior.

One non-standard attribute is defined here:

recipient_list¶

The list of email addresses to send mail to. If not specified, defaults to the recipient_list of the form.

Additionally, the following standard (from FormView) methods and attributes are commonly useful to override (all attributes below can also be passed to as_view() in the URLconf, permitting customization without the need to write a full custom subclass of ContactFormView):

form_class¶

The form class to use. By default, will be ContactForm. This can also be overridden as a method named form_class(); this permits, for example, per-request customization (by inspecting attributes of self.request).

template_name¶

The template to use when rendering the form. By default, will be contact_form/contact_form.html.

get_success_url()¶

The URL to redirect to after successful form submission. By default, this is the named URL contact_form.sent. In the default URLconf provided with django-contact-form, that URL is mapped to TemplateView rendering the template contact_form/contact_form_sent.html.

get_form_kwargs()¶

Returns additional keyword arguments (as a dictionary) to pass to the form class on initialization.

By default, this will return a dictionary containing the current HttpRequest (as the key request) and, if recipient_list was defined, its value (as the key recipient_list).

Warning

If you override get_form_kwargs(), you must ensure that, at the very least, the keyword argument request is still provided, or ContactForm initialization will raise TypeError. The simplest approach is to use super() to call the base implementation in ContactFormView, and modify the dictionary it returns.

Warning

Implementing form_invalid()

To work around a potential performance issue in Django 1.9, ContactFormView implements the form_invalid() method. If you choose to override form_invalid() in a subclass of ContactFormView, be sure to read the implementation and comments in the source code of django-contact-form first. Note that Django 1.9.1, once released, will not be affected by this bug.

Frequently asked questions¶

The following notes answer some common questions, and may be useful to you when installing, configuring or using django-contact-form.