Contact form classes¶
There are three contact-form classes included in django-contact-form-recaptcha; one provides all the infrastructure for a contact form, and will usually be the base class for subclasses which want to extend or modify functionality. The other two are subclasses which add spam filtering to the contact form.
The ContactForm class¶
-
class
contact_form.forms.
ContactForm
¶ The base contact form class from which all contact form classes should inherit.
If you don’t need any customization, you can use this form to provide basic contact-form functionality; it will collect name, email address, subject and message.
The
ContactFormView
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, here’s how:- When you instantiate the form, pass the current
HttpRequest
object as the keyword argumentrequest
; 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). - To send the message, call the form’s
save
method, which accepts the keyword argumentfail_silently
and defaults it toFalse
. This argument is passed directly to Django’ssend_mail()
function, and allows you to suppress or raise exceptions as needed for debugging. Thesave
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 thecleaned_data
dictionary.Under the hood, this form uses a somewhat abstracted interface in order to make it easier to subclass and add functionality.
The following attributes play a role in determining behavior, and any of them can be implemented as an attribute or as a method (for example, if you wish to have
from_email
be dynamic, you can implement a method namedfrom_email()
instead of setting the attributefrom_email
):-
from_email
¶ The email address to use in the
From:
header of the message. By default, this is the value of the settingDEFAULT_FROM_EMAIL
.
-
recipient_list
¶ The list of recipients for the message. By default, this is the email addresses specified in the setting
MANAGERS
.
-
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
.
-
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 producing the contents of the message to send:
-
message
()¶ Returns the body of the message to send. By default, this is accomplished by rendering the template name specified in
template_name
.
-
subject
()¶ Returns the subject line of the message to send. By default, this is accomplished by rendering the template name specified in
subject_template_name
.
Finally, the message itself is generated by the following two methods:
-
get_message_dict
()¶ This method loops through
from_email
,recipient_list
,message()
andsubject()
, collecting those parts into a dictionary with keys corresponding to the arguments to Django’ssend_mail
function, then returns the dictionary. Overriding this allows essentially unlimited customization of how the message is generated. Note that for compatibility, implementations which override this should support callables for the values offrom_email
andrecipient_list
.
-
get_context
()¶ For methods which render portions of the message using templates (by default,
message()
andsubject()
), generates the context used by those templates. The default context will be aRequestContext
(using the current HTTP request, so user information is available), plus the contents of the form’scleaned_data
dictionary, and one additional variable:site
- If
django.contrib.sites
is installed, the currently-activeSite
object. Otherwise, aRequestSite
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.
-
request
¶ The
HttpRequest
object representing the current request. This is set automatically in__init__()
, and is used both to generate aRequestContext
for the templates and to allow subclasses to engage in request-specific behavior.
-
save
()¶ If the form has data and is valid, will send the email, by calling
get_message_dict()
and passing the result to Django’ssend_mail
function.
Note that subclasses which override
__init__
orsave()
need to accept*args
and**kwargs
, and pass them viasuper
, 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).- When you instantiate the form, pass the current
The ReCaptcha (spam-filtering) contact form class¶
-
class
contact_form.forms.
ReCaptchaContactForm
¶ A subclass of
ContactForm
which adds spam filtering, via the Google reCAPTCHA spam-detection service.Use of this class requires you to provide configuration for the reCAPTCHA web service; you’ll need to obtain the reCAPTCHA API keys. You can do this at <https://www.google.com/recaptcha>. Once you have, you can configure in either of two ways:
- Put your reCAPTCHA API keys in the Django settings
RECAPTCHA_PUBLIC_KEY
andRECAPTCHA_PRIVATE_KEY
, or - Put your reCAPTCHA API keys in the environment variables
PYTHON_RECAPTCHA_PUBLIC_KEY
andPYTHON_RECAPTCHA_PRIVATE_KEY
.
You will also need the Python reCAPTCHA module to communicate with the reCAPTCHA web service. You can install it by running
pip install django-recaptcha
, or django-contact-form-recaptcha installs it automatically for you when you runpip install django-contact-form-recaptcha
.Once you have the reCAPTCHA API keys configured, and the
django-recaptcha
module installed, you can drop inReCaptchaContactForm
anywhere you would have usedContactForm
. For example, you could define a view (subclassingContactFormView
) like so, and then point a URL at it:from contact_form.forms import ReCaptchaContactForm from contact_form.views import ContactFormView class ReCaptchaContactFormView(ContactFormView): form_class = ReCaptchaContactForm
Or directly specify the form in your URLconf:
from django.conf.urls import url from contact_form.forms import ReCaptchaContactForm from contact_form.views import ContactFormView urlpatterns = [ # other URL patterns... url(r'^contact-form/$', ContactForm.as_view( form_class=ReCaptchaContactForm ), name='contact_form'), ]
- Put your reCAPTCHA API keys in the Django settings