Skip to content

Latest commit

 

History

History
186 lines (129 loc) · 5.97 KB

usage.rst

File metadata and controls

186 lines (129 loc) · 5.97 KB

Usage guide

First you'll need to have Django and django-contact-form installed. For details on that, see :ref:`the installation guide <install>`.

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 :class:`~django_contact_form.views.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 :class:`~django.template.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 :class:`~django.template.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 :class:`~django.template.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 :class:`~django.contrib.sites.models.Site` or :class:`~django.contrib.sites.requests.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 :class:`~django.template.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 :class:`~django.contrib.sites.models.Site` or :class:`~django.contrib.sites.requests.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: :class:`~django_contact_form.forms.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")),
]