django-fwdform 0.1.0
Simple and painless form processing for static sites.
License: BSD
Keywords: django-fwdform

=============================
django-fwdform
=============================

.. image:: http://img.shields.io/travis/mishbahr/django-fwdform.svg?style=flat-square
    :target: https://travis-ci.org/mishbahr/django-fwdform/

.. image:: http://img.shields.io/pypi/v/django-fwdform.svg?style=flat-square
    :target: https://pypi.python.org/pypi/django-fwdform/
    :alt: Latest Version

.. image:: http://img.shields.io/pypi/dm/django-fwdform.svg?style=flat-square
    :target: https://pypi.python.org/pypi/django-fwdform/
    :alt: Downloads

.. image:: http://img.shields.io/pypi/l/django-fwdform.svg?style=flat-square
    :target: https://pypi.python.org/pypi/django-fwdform/
    :alt: License

.. image:: http://img.shields.io/coveralls/mishbahr/django-fwdform.svg?style=flat-square
  :target: https://coveralls.io/r/mishbahr/django-fwdform?branch=master

Simple and painless form processing for static sites.


Why?
----

I have several sites hosted on AWS S3 for pennies a month... and I didn't want to
pay $20 per month (per form) for processing contact forms!

**20+ domains powered by 1 Heroku app = Profit!**


Demo
----

See https://github.com/mishbahr/staticgen-fwdform

Features
--------

* Multi site support.
* Unlimited forms
* Unlimited submissions
* Spam Protection via Akismet.
* Submit forms with AJAX.
* REST API to manage forms.


Quickstart
----------

1. Install ``django-fwdform``::

    pip install django-fwdform

2. Add ``fwdform`` to ``INSTALLED_APPS``::

    INSTALLED_APPS = (
        ...
        'corsheaders',
        'fwdform',
        ...
    )

3. Sync database::

    python manage.py migrate


4. Add ``fwdform.urls`` to your project's urls module::

    urlpatterns = patterns(
        ...
        url(r'^', include('fwdform.urls', namespace='fwdform')),
        ...
    )



Dependencies
------------

This package requires ``django-cors-headers`` to be installed and configured correctly. When ``django-fwdform`` is installed using pip, ``django-cors-headers`` is automatically installed.

You will need to add corsheaders middleware class to ``MIDDLEWARE_CLASSES`` settings::

    MIDDLEWARE_CLASSES = (
        ...
        'corsheaders.middleware.CorsMiddleware',
        'django.middleware.common.CommonMiddleware',
        ...
    )

Note that ``CorsMiddleware`` needs to come before Django's ``CommonMiddleware``.

Allow CORS requests from all domains::

    CORS_ORIGIN_ALLOW_ALL = True

For more information, see https://github.com/ottoyiu/django-cors-headers


Sample Form
-----------

::

    <form action="//example.com/send/<form_hash>/" method="POST">
        <input type="text" name="name" required="required"/>
        <input type="email" name="email" required="required" />
        <textarea name="message" rows="5"></textarea>
        <input type="submit" value="Send">
    </form>


Special Form Inputs
*******************

**_next**

By default, after submitting a form the user is shown the FwdForm "Thank You" page. You can provide an alternative URL for that page. ::

    <input type="hidden" name="_next" value="//example.com/thanks.html" />


**_subject**

This value is used for the email's subject::

    <input type="hidden" name="_subject" value="Contact Form" />

**_gotcha**

Add this "honeypot" field. If a value is provided, the submission will be silently ignored. The input should be hidden with CSS::

    <input type="text" name="_gotcha" style="display:none;" />

**name/email/message**

Span prevention via Akismet - Spam checker backend looks for these specially named form inputs::

    <input type="text" name="name" placeholder="Your Name">
    <input type="email" name="email" placeholder="Your Email">
    <textarea name="message" rows="5"></textarea>

Rest API
--------

Register a form, this returns a hashid for the newly created form::

    $ curl --data "name=Contact%20Form&recipients=conttact@example.com" http://example.com/<site_token>/
    {"hashid": "0rPGVlYZWqMRE8OebjoM1ogpmvNL23A9dxJzywQD"}

Update existing form config by passing a known ``hashid`` as a param::

    $ curl --data "recipients=hello@example.com&hashid=0rPGVlYZWqMRE8OebjoM1ogpmvNL23A9dxJzywQD" http://example.com/<site_token>/


AJAX Submission
---------------

You can use fwdform via AJAX. This even works cross-origin.

If you're using jQuery this can be done like so::

    $.ajax({
        url: $form.attr("action"),
        method: "POST",
        data: $form.serialize(),
        dataType: "json",
        headers: {"X-Requested-With": "XMLHttpRequest"},
    });