Commits

Anonymous committed cb8970b

Hooray documentation

Comments (0)

Files changed (6)

contact_form/forms.py

           
         * ``template_name`` -- used by the base ``message`` method
           to determine which template to use for rendering the
-          message. Default is ``contact/contact_form.txt``
+          message. Default is ``contact_form/contact_form.txt``.
           
     Internally, the base implementation ``_get_message_dict`` method
     collects ``from_email``, ``message``, ``recipients`` and
     
     subject = "[%s] Message sent through the web site" % Site.objects.get_current().name
     
-    template_name = 'contact/contact_form.txt'
+    template_name = 'contact_form/contact_form.txt'
     
     def message(self):
         """
                            name='contact_form'),
                        url(r'^contact/sent/$',
                            direct_to_template,
-                           { 'template': 'contact/contact_form_sent.html' },
+                           { 'template': 'contact_form/contact_form_sent.html' },
                            name='contact_form_sent'),
                        )

contact_form/views.py

 from django.contrib.auth.views import redirect_to_login
 from contact_form.forms import ContactForm
 
-def contact_form(request, form_class=ContactForm, template_name='contact/contact_form.html', success_url='/contact/sent/', login_required=False, fail_silently=False):
+def contact_form(request, form_class=ContactForm, template_name='contact_form/contact_form.html', success_url='/contact/sent/', login_required=False, fail_silently=False):
     """
     Renders a contact form, validates its input and sends an email
     from it.
     template used to render the email message sent from the form,
     which is handled by the form class), pass the ``template_name``
     keyword argument; if not supplied, this will default to
-    ``contact/contact_form.html``.
+    ``contact_form/contact_form.html``.
     
     To specify a URL to redirect to after a successfully-sent message,
     pass the ``success_url`` keyword argument; if not supplied, this
+=====================
+Included form classes
+=====================
+
+
+Two form classes are included with this application; one,
+``contact_form.forms.ContactForm`` implements the necessary base
+functionality of a contact form, and other contact-form classes should
+inherit from it to receive that functionality. The other,
+contact_form.forms.AkismetContactForm``, is a subclass of
+``ContactForm`` provided both because it is useful and as a
+demonstration of subclassing ``ContactForm``.
+
+
+``contact_form.forms.ContactForm``
+==================================
+
+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 ``contact_form`` 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.
+       
+    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.
+
+
+Base implementation
+-------------------
+
+Under the hood, this form uses a somewhat abstracted interface in
+order to make it easier to subclass and add functionality. There
+are several important attributes subclasses may want to look at
+overriding, all of which will work (in the base implementation) as
+either plain attributes or as callable methods:
+
+    * ``from_email`` -- used to get the address to use in the
+      ``From:`` header of the message. The base implementation
+      returns the value of the ``DEFAULT_FROM_EMAIL`` setting.
+      
+    * ``message`` -- used to get the message body as a string. The
+      base implementation renders a template using the form's
+      ``cleaned_data`` dictionary as context.
+      
+    * ``recipients`` -- used to generate the list of recipients
+      for the message. The base implementation returns the email
+      addresses specified in the ``MANAGERS`` setting.
+      
+    * ``subject`` -- used to generate the subject line for the
+      message. The base implementation returns the string 'Message
+      sent through the web site', with the name of the current
+      ``Site`` prepended.
+      
+    * ``template_name`` -- used by the base ``message`` method
+      to determine which template to use for rendering the
+      message. Default is ``contact/contact_form.txt``
+      
+Internally, the base implementation ``_get_message_dict`` method
+collects ``from_email``, ``message``, ``recipients`` and
+``subject`` into a dictionary, which the ``save`` method then
+passes directly to ``send_mail`` as keyword arguments.
+
+Particularly important is the ``message`` attribute, with its base
+implementation as a method which renders a template; because it
+passes ``cleaned_data`` as the template context, any additional
+fields added by a subclass will automatically be available in the
+template. This means that many useful subclasses can get by with
+just adding a few fields and possibly overriding ``template_name``.
+
+Much useful functionality can be achieved in subclasses without
+having to override much of the above; adding additional validation
+methods works the same as any other form, and typically only a few
+items -- ``recipient_list`` and ``subject_line``, for example,
+need to be overridden to achieve customized behavior.
+
+
+Other notes for subclassing
+---------------------------
+
+Subclasses which want to inspect the current ``HttpRequest`` to
+add functionality can access it via the attribute ``request``; the
+base ``message`` takes advantage of this to use ``RequestContext``
+when rendering its template. See the ``AkismetContactForm``
+subclass in this file for an example of using the request to
+perform additional validation.
+
+Subclasses which override ``__init__`` need to accept ``*args``
+and ``**kwargs``, and pass them via ``super`` in order to ensure
+proper behavior.
+
+Subclasses should be careful if overriding ``_get_message_dict``,
+since that method **must** return a dictionary suitable for
+passing directly to ``send_mail`` (unless ``save`` is overridden
+as well).
+
+Overriding ``save`` is relatively safe, though remember that code
+which uses your form will expect ``save`` to accept the
+``fail_silently`` keyword argument. In the base implementation,
+that argument defaults to ``False``, on the assumption that it's
+far better to notice errors than to silently not send mail from
+the contact form (see also the Zen of Python: "Errors should never
+pass silently, unless explicitly silenced").
+
+
+``contact_form.forms.AkismetContactForm``
+=========================================
+
+Contact form which doesn't add any extra fields, but does add an
+Akismet spam check to the validation routine.
+
+Requires the setting ``AKISMET_API_KEY``, which should be a valid
+Akismet API key.
+================================
+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 three templates: ``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 two templates; the third 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.
+==============
+Included views
+==============
+
+
+One view is included with this application:
+``contact_form.views.contact_form``, which knows how to work with
+``contact_form.forms.ContactForm`` and its subclasses, and takes
+several useful keyword arguments for specifying behavior.
+
+
+``contact_form.views.contact_form``
+====================================
+
+Renders a contact form, validates its input and sends an email
+from it.
+
+To specify the form class to use, pass the ``form_class`` keyword
+argument; if no ``form_class`` is specified, the base
+``ContactForm`` class will be used.
+
+To specify the template to use for rendering the form (*not* the
+template used to render the email message sent from the form,
+which is handled by the form class), pass the ``template_name``
+keyword argument; if not supplied, this will default to
+``contact/contact_form.html``.
+
+To specify a URL to redirect to after a successfully-sent message,
+pass the ``success_url`` keyword argument; if not supplied, this
+will default to ``/contact/sent/``.
+
+To allow only registered users to use the form, pass a ``True``
+value for the ``login_required`` keyword argument.
+
+To suppress exceptions raised during sending of the email, pass a
+``True`` value for the ``fail_silently`` keyword argument. This is
+**not** recommended.
+    
+Template::
+
+    Passed in the ``template_name`` argument.
+    
+Context::
+
+    form
+        The form instance.