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
|
================================
Generic contact forms for Django
================================
Providing some sort of contact or feedback form for soliciting
information from site visitors is a common need in web development,
and writing a contact form and associated handler view, while
relatively straightforward to do with Django, can be a tedious and
repetitive task. This application aims to remove or reduce that tedium
and repetition by providing generic contact-form functionality.
Requirements
============
This application makes heavy use of Django's newforms library, and was
written *after* a backwards-incompatible change on Django trunk
altered the way newforms stores valid data; as a result, this
application requires a Subversion checkout of Django, revision 5237 or
later.
Because a recent trunk checkout of Django was already required, the
default ``urls.py`` supplied with this application also takes
advantage of named URL patterns, a feature which was not present in
the Django 0.96 release.
If you will be using the included ``AkismetContactForm`` class, which
performs an Akismet spam check as part of its validation, you will
need the `Python Akismet module`_ and a valid Akismet API key; you can
obtain an Akismet API by following the instructions at `the Akismet
web site`_.
.. _Python Akismet module: http://www.voidspace.org.uk/python/modules.shtml#akismet
.. _the Akismet web site: http://akismet.com/
High-level overview
===================
This application contains a (newforms) form class called
``ContactForm``, which implements a useful baseline for contact forms
-- collecting a name, email address and message, and emailing them to
site staff -- and which is also designed so as to allow additional
functionality to be added easily in subclasses. For specifics of how
``ContactForm`` works and what to look at when subclassing it, see the
`forms documentation`_ included with this application.
Also provided is a generic-style view called ``contact_form``, which
is designed to work out-of-the-box with ``ContactForm`` and subclasses
of ``ContactForm``, and has a number of configurable parameters to
allow specification of the form class to use, whether to require a
user to log in before using the form, etc. For full details on this
view and the options it provides, see the `views_documentation`_
included with this application.
A sample URLConf is included, and can be used "as-is" if the default
``ContactForm`` and default parameters of the ``contact_form`` view
are all that's required, or studied as an example.
.. _forms documentation: forms.html
.. _views documentation: views.html
Basic usage
===========
To get up and running immediately using the default setup, do the
following:
* Add ``contact_form`` to your project's ``INSTALLED_APPS``
setting. You will *not* need to run ``manage.py syncdb``, since
this application provides no models.
* In your root URLConf, add the following URL pattern::
(r'^contact/', include('contact_form.urls'),
* Create four templates: ``contact_form/contact_form_subject.txt``
and ``contact_form/contact_form.txt``, which will be used to
render the email messages sent by the form;
``contact_form/contact_form.html``, which will be used to
display the form to users; and
``contact_form/contact_form_sent.html``, which will be used
after the form is successfully submitted. See the forms and
views documentation, respectively, for details on the contexts
available to the first three templates; the fourth is rendered
from the ``direct_to_template`` generic view, and has no
context.
Once this is done, visiting the URL ``/contact/`` on your site will
display the contact form, and submitting it will send an email to each
address in the ``MANAGERS`` setting for your project.
|
