1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
|
.. _quickstart:
Quick start 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. First,
add `'django_contact_form'` to your
:data:`~django.conf.settings.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/`:
.. code-block:: python
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:
.. code-block:: python
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 an application you've written.
Required templates
------------------
The two views above will need several templates to be created.
`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 typed.
`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
<https://docs.djangoproject.com/en/1.11/ref/contrib/sites/>`_ 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 typed.
`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
<https://docs.djangoproject.com/en/1.11/ref/contrib/sites/>`_ is
installed).
.. warning:: **Subject must be a single line**
In order to prevent `header injection attacks
<https://en.wikipedia.org/wiki/Email_injection>`_, 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 Wordpress Akismet spam-detection service
<https://akismet.com/>`_.
To use this form, you will need to do the following things:
1. Install the Python `akismet` module to allow django-contact-form
to communicate with the Akismet service. You can do this via `pip
install akismet`, or as you install django-contact-form via `pip
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. You can
either place them in the Django settings
:data:`~django.conf.settings.AKISMET_API_KEY` and
:data:`~django.conf.settings.AKISMET_BLOG_URL`, or in the
environment variables `PYTHON_AKISMET_API_KEY` and
`PYTHON_AKISMET_BLOG_URL`.
Then you can replace the suggested URLconf above with the following:
.. code-block:: python
from django.urls import include, path
urlpatterns = [
# ... other URL patterns for your site ...
path('contact/', include('django_contact_form.akismet_urls')),
]
|
