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:

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]".
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, 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")),
]