Author: Stephen McDonald


        .. image::


Created by `Stephen McDonald <>`_

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


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 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::

        # other apps

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

        # other context processors
        # Django 1.6 also needs:

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

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

    from django.contrib import admin

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

Finally, sync your database::

    $ python 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 migrate forms


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 %}
    {% 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.