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 simply begin using it right away.
URL configuration¶
The easiest way to set up the views in django-contact-form is to
just 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’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.