django-forms-builder

HomePage: http://github.com/stephenmcd/django-forms-builder

Author: Stephen McDonald

Download: https://pypi.python.org/packages/source/d/django-forms-builder/django-forms-builder-0.10.tar.gz

        .. image:: https://secure.travis-ci.org/stephenmcd/django-forms-builder.png?branch=master
   :target: http://travis-ci.org/#!/stephenmcd/django-forms-builder

django-forms-builder
====================

Created by `Stephen McDonald <http://twitter.com/stephen_mcd>`_

A Django reusable app providing the ability for admin users to create
their own forms within the admin interface drawing from a range of
field widgets such as regular text fields, drop-down lists and file
uploads. Options are also provided for controlling who gets sent email
notifications when a form is submitted. All form entries are made
available in the admin via CSV export.

HTML5 Features
==============

The following HTML5 form features are supported.

* ``placeholder`` attributes
* ``required`` attributes
* ``email`` fields
* ``date`` fields
* ``datetime`` fields
* ``number`` fields
* ``url`` fields

Installation
============

The easiest way to install django-forms-builder is directly from PyPi
using `pip`_ by running the command below::

    $ pip install -U django-forms-builder

Otherwise you can download django-forms-builder and install it directly
from source::

    $ python setup.py install

Project Configuration
=====================

Once installed you can configure your project to use
django-forms-builder with the following steps.

Add ``forms_builder.forms`` to ``INSTALLED_APPS`` in your project's
``settings`` module::

    INSTALLED_APPS = (
        # other apps
        'forms_builder.forms',
    )

If you haven't already, ensure ``django.core.context_processors.request``
is in the ``TEMPLATE_CONTEXT_PROCESSORS`` setting in your project's
``settings`` module::

    TEMPLATE_CONTEXT_PROCESSORS = (
        # other context processors
        "django.core.context_processors.request",
        # Django 1.6 also needs:
        'django.contrib.auth.context_processors.auth',
    )

Then add ``forms_builder.forms.urls`` to your project's ``urls``
module::

    from django.conf.urls.defaults import patterns, include, url
    import forms_builder.forms.urls # add this import

    from django.contrib import admin
    admin.autodiscover()

    urlpatterns = patterns('',
        # other urlpatterns
        url(r'^admin/', include(admin.site.urls)),
        url(r'^forms/', include(forms_builder.forms.urls)),
    )

Finally, sync your database::

    $ python manage.py syncdb

As of version 0.5, django-forms-builder provides `South`_ migrations. If
you use south in your project, you'll also need to run migrations::

    $ python manage.py migrate forms

Usage
=====

Once installed and configured for your project just go to the admin
page for your project and you will see a new Forms section. In this
you can create and edit forms. Forms are then each viewable with their
own URLs. A template tag ``render_built_form`` is also available for
displaying forms outside of the main form view provided. It will
display a form when given an argument in one of the following
formats, where ``form_instance`` is an instance of the ``Form`` model::

    {% render_built_form form_instance %}
    {% render_built_form form=form_instance %}
    {% render_built_form id=form_instance.id %}
    {% render_built_form slug=form_instance.slug %}

This allows forms to be displayed without having a form instance, using
a form's slug or ID, which could be hard-coded in a template, or stored
in another model instance.

File Uploads
============

It's possible for admin users to create forms that allow file uploads
which can be accessed via a download URL for each file that is provided
in the CSV export. By default these uploaded files are stored in an
obscured location under your project's ``MEDIA_ROOT`` directory but
ideally the should be stored somewhere inaccessible to the public. To
set the location where files are stored to be somewhere outside of your
project's ``MEDIA_ROOT`` directory you just need to define the
``FORMS_BUILDER_UPLOAD_ROOT`` setting in your project's ``settings``
module. Its value should be an absolute path on the web server that
isn't accessible to the public.

Con