.. _forms:
.. 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 :class:`~contact_form.views.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, 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).