================================
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.