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
|
.. _usage:
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/``:
.. 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 a
Django application you've written.
.. _default-templates:
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
<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 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
<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 Akismet
spam-detection service <https://akismet.com/>`_.
To use this form, you will need to do the following things:
1. Install `the Python akismet client <https://akismet.readthedocs.io/>`_ 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:
.. code-block:: python
from django.urls import include, path
urlpatterns = [
# ... other URL patterns for your site ...
path("contact/", include("django_contact_form.akismet_urls")),
]
|
