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 variableform
. 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 viapip install akismet
, or as you install django-contact-form viapip 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
andAKISMET_BLOG_URL
, or in the environment variablesPYTHON_AKISMET_API_KEY
andPYTHON_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')),
]