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
|
.. module:: contact_form.forms
The ContactForm class
=====================
.. class:: ContactForm
The base contact form class from which all contact form classes
should inherit.
If you don't need any custom functionality, you can simply use
this form to provide basic contact functionality; it will collect
name, email address and message.
The ContactForm view included in this application knows how
to work with this form and can handle many types of subclasses as
well (see below for a discussion of the important points), so in
many cases it will be all that you need. If you'd like to use this
form or a subclass of it from one of your own views, just do the
following:
1. When you instantiate the form, pass the current ``HttpRequest``
object to the constructor as the keyword argument ``request``;
this is used internally by the base implementation, and also
made available so that subclasses can add functionality which
relies on inspecting the request (such as spam filtering).
2. To send the message, call the form's ``save`` method, which
accepts the keyword argument ``fail_silently`` and defaults it
to ``False``. This argument is passed directly to
``send_mail``, and allows you to suppress or raise exceptions
as needed for debugging. The ``save`` method has no return
value.
Other than that, treat it like any other form; validity checks and
validated data are handled normally, through the ``is_valid``
method and the ``cleaned_data`` dictionary.
Under the hood, this form uses a somewhat abstracted interface in
order to make it easier to subclass and add functionality.
These attributes play a role in determining behavior:
.. attribute:: from_email
The email address to use in the ``From:`` header of the
message. This can also be implemented as a method named
``from_email()``, in which case it will be called when
constructing the message. By default, this is the value of the
setting ``DEFAULT_FROM_EMAIL``.
.. attribute:: recipient_list
The list of recipients for the message. This can also be
implemented as a method named ``recipient_list()``, in which
case it will be called when constructing the message. By
default, this is the email addresses specified in the setting
``MANAGERS``.
.. attribute:: subject_template_name
The name of the template to use when rendering the subject line
of the message. By default, this is
``contact_form/contact_form_subject.txt``.
.. attribute:: template_name
The name of the template to use when rendering the body of the
message. By default, this is ``contact_form/contact_form.txt``.
And two methods are involved in actually producing the contents of
the message to send:
.. method:: message()
Returns the body of the message to send. By default, this is
accomplished by rendering the template name specified in
:attr:`template_name`.
.. method:: subject()
Returns the subject line of the message to send. By default,
this is accomplished by rendering the template name specified
in :attr:`subject_template_name`.
Finally, the message itself is generated by the following two
methods:
.. method:: get_message_dict()
This method loops through :attr:`from_email`,
:attr:`recipient_list`, :meth:`message` and :meth:`subject`,
collecting those parts into a dictionary with keys
corresponding to the arguments to Django's ``send_mail``
function, then returns the dictionary. Overriding this allows
essentially unlimited customization of how the message is
generated.
.. method:: get_context()
For methods which render portions of the message using
templates (by default, :meth:`message` and :meth:`subject`),
generates the context used by those templates. The default
context will be a ``RequestContext`` (using the current HTTP
request, so user information is available), plus the contents
of the form's ``cleaned_data`` dictionary, and one additional
variable:
``site``
If ``django.contrib.sites`` is installed, the
currently-active ``Site`` object. Otherwise, a
``RequestSite`` object generated from the request.
Meanwhile, the following attributes/methods generally should not
be overridden; doing so may interfere with functionality, may not
accomplish what you want, and generally any desired customization
can be accomplished in a more straightforward way through
overriding one of the attributes/methods listed above.
.. attribute:: request
The ``HttpRequest`` object representing the current
request. This is set automatically in ``__init__()``, and is
used both to generate a ``RequestContext`` for the templates
and to allow subclasses to engage in request-specific behavior.
.. method:: save
If the form has data and is valid, will actually send the
email, by calling :meth:`get_message_dict` and passing the
result to Django's ``send_mail`` function.
Note that subclasses which override ``__init__`` or :meth:`save`
need to accept ``*args`` and ``**kwargs``, and pass them via
``super``, in order to preserve behavior (each of those methods
accepts at least one additional argument, and this application
expects and requires them to do so).
|
