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 begin using it right away.

URL configuration¶

The quicket way to set up the views in django-contact-form is to 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’re using Django 2.0, and want to use the new-style URL configuration, instead you can do:

from django.conf.urls import include, path

urlpatterns = [

# … other URL patterns for your site … path(‘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'),
]

Important

Where to put custom forms and views

When writing a custom form class (or custom ContactFormView subclass), don’t put your custom code inside django-contact-form. Instead, put your custom code in the appropriate place (a forms.py or views.py file) in an application you’ve written.

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

Warning

Subject must be a single line

In order to prevent header injection attacks, the subject must be only a single line of text, and Django’s email framework will reject any attempt to send an email with a multi-line subject. So it’s a good idea to ensure your contact_form_subject.txt template only produces a single line of output when rendered; as a precaution, however, django-contact-form will split the output of this template at line breaks, then forcibly re-join it into a single line of text.

Using a spam-filtering contact form¶

Spam filtering is a common desire for contact forms, due to the large amount of spam they can attract. There is a spam-filtering contact form class included in django-contact-form: AkismetContactForm, which uses the Wordpress Akismet spam-detection service.

To use this form, you will need to do the following things:

Install the Python akismet module to allow django-contact-form to communicate with the Akismet service. You can do this via pip install akismet, or as you install django-contact-form via pip install django-contact-form[akismet].
Obtain an Akismet API key from <https://akismet.com/>, and associate it with the URL of your site.
Supply the API key and URL for django-contact-form to use. You can either place them in the Django settings AKISMET_API_KEY and AKISMET_BLOG_URL, or in the environment variables PYTHON_AKISMET_API_KEY and PYTHON_AKISMET_BLOG_URL.

Then you can replace the suggested URLconf above with the following:

from django.conf.urls import include, url


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