Skip to content
Back to top
View this page

# Usage 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. Add `"django_contact_form"` to your `INSTALLED_APPS` setting. Then, you can begin configuring.

## URL configuration

The quickest way to set up the views in `django-contact-form` is to use the provided URLconf, found at `django_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.urls import include, path

    urlpatterns = [
        # ... other URL patterns for your site ...
        path("contact/", include("django_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.urls import include, path
    from django.views.generic import TemplateView

    from django_contact_form.views import ContactFormView

    from yourapp.forms import YourCustomFormClass

    urlpatterns = [
        # ... other URL patterns for your site ...
        path("contact/",
            ContactFormView.as_view(
                form_class=YourCustomFormClass
            ),
            name="django_contact_form"),
        path("contact/sent/",
            TemplateView.as_view(
                template_name="django_contact_form/contact_form_sent.html"
            ),
            name="django_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 a Django application you’ve written.

## Required templates

In the default configuration, `django-contact-form` requires the following templates to exist:

### `django_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`.

### `django_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.

### `django_contact_form/contact_form.txt`

Used to render the subject of the email. Will receive a `RequestContext` with the following additional variables:

`body`

  The message the user supplied.

`email`

  The email address the user supplied.

`name`

  The name the user supplied.

`site`

  The current site. Either a `Site` or `RequestSite` instance, depending on whether Django’s sites framework is installed).

### `django_contact_form/contact_form_subject.txt`

Used to render the subject of the email. Will receive a `RequestContext` with the following additional variables:

`body`

  The message the user supplied.

`email`

  The email address the user supplied.

`name`

  The name the user supplied.

`site`

  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, by default, condense the output of this template to a single line.

## 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 Akismet spam-detection service.

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

1. Install the Python akismet client to allow `django-contact-form` to communicate with the Akismet service. You can do this manually (in which case you must install at least version 24.5.0 of `akismet`) or as you install `django-contact-form` by telling `pip` to install `"django-contact-form[akismet]"`.

2. Obtain an Akismet API key from <https://akismet.com/>, and associate it with the URL of your site.

3. Supply the API key and URL for `django-contact-form` to use, by placing them 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.urls import include, path

    urlpatterns = [
        # ... other URL patterns for your site ...
        path("contact/", include("django_contact_form.akismet_urls")),
    ]