django-formfactory 0.1

Django Form Factory
===================
**Dynamic django form builder.**

.. image:: https://travis-ci.org/praekelt/django-formfactory.svg?branch=develop
:target: https://travis-ci.org/praekelt/django-formfactory

.. image:: https://coveralls.io/repos/github/praekelt/django-formfactory/badge.svg?branch=develop
:target: https://coveralls.io/github/praekelt/django-formfactory?branch=develop

.. contents:: Contents
:depth: 5

Installation
------------

#. Install or add ``django-formfactory`` to your Python path.

#. Add ``formfactory`` to your ``INSTALLED_APPS`` setting.

#. Add ``url(r'^formfactory/', include("formfactory.urls", namespace="formfactory"))`` to your ``url patterns`` (only required if you intend on using the detail view)

Usage
-----

``django-formfactory`` allows users to create forms and wizards in the CMS.

Settings
~~~~~~~~

FORMFACTORY["field-types"]
Control the form fields types that can be selected in Admin.

Views
~~~~~

``django-formfactory`` provide a base ``FormView`` and ``FactoryWizardView``
which can both be used directly or subclassed if you require extra context
or form data processing.

Templates
~~~~~~~~~

``django-formfactory`` allows you to either override the template for all forms
by adding a template ``formfactory/form_detail.html`` or an individual form by
adding a template ``formfactory/form_detail_<form-slug>.html`` to your project's
template dir.

Inclusiontag
~~~~~~~~~~~~

Use the inclusion tag which has been provided:
``{% render_form form_object %}``


Models
~~~~~~

**FormData:**
A basic store for user submitted form data.
- uuid: a common uuid for each data item in the data set
- form: the ``Form`` object

**FormDataItem:**
A per field value store, encapsulated by a ``FormData`` object.
- form_data: the ``FormData`` object
- form_field: the ``FormField`` object
- value: a text value of what was submitted for a particular field

**Action:**
An action which will be triggered in order when the form is saved.
- action: a choice of all registered actions in the project
- as_function: a property which returns the action function

**ActionParam:**
Params that are required by the predefined or custom action functions. Passed to the action as a set of kwargs.
- key: param name
- value: param value
- action: the ``Action`` object

**Form:**
A form object which encapsulates a set of form fields and defines the actions that will be performed on save.
- title: a descriptive title
- slug: url friendly identifier
- actions: a set of ``Action`` objects to be performed in order on save
- success_message: The message string that will be displayed by the django messages framework on successful submission of the form
- failure_message: The message string that will be displayed by the django messages framework if a form submission fails


**Wizard:**
A wizard object that encapsulates a list of forms and actions that will be performed on the WizardView's ``done`` step.
- title: a descriptive title
- slug: url friendly identifier
- forms: a set of ordered forms mapping to each step in the WizardView.
- redirect_to: The URL which should should be redirect to after the wizard's done step (e.g. "/").
- actions: a set of ordered ``Action`` objects to be performed in order in the WizardView's ``done`` step.
- success_message: The message string that will be displayed by the django messages framework on successful submission of the form
- failure_message: The message string that will be displayed by the django messages framework if a form submission fails

Each form's ``save()`` method is called in the ``done`` step. This ensures that all actions defined for each form are
performed. Following that, wizard actions are then performed before the WizardView redirects.

The URL to which the WizardView redirects can be specified in one of two ways:
- It can be specified in the CMS in the ``redirect_to`` field on the wizard object.
- It can be specified as a GET query parameter on the URL. The query parameter key can be specified by setting
``FORMFACTORY["redirect-url-param-name"]`` in your settings file.

**FieldChoice:**
A set of field choices that a populated into `MultiSelect` and `Select` widgets
- label: human readable dropdown label
- value: the value that will be submitted

**FormFieldGroup:**
A model which encapsulates a set of form fields.
- title: the title to be used in the formset legend when rendered
- forms: the ``Form``s this grouping is associated to

**FormField:**
Defines a form field with all options and required attributes. Encapsulated by the ``Form`` object.
- title: a descriptive title
- slug: url friendly identifier
- position: the position at which the field should be rendered in the form
- form_groups: the ``FormFieldGroup``s this field is associated to
- field_type: a set of field type, defined in the app settings
- widget: a set of widgets, defined in app settings
- label: the field label text
- initial: an initial value the field will be populated with
- max_length: the maximum length a value can be
- help_text: a helpful string that will be rendered below the field
- placeholder: a string that will be rendered as the field placeholder
- required: boolean value to indicate if the field is required
- disabled: boolean value to disable field (readonly)
- choices: a set of ``FieldChoice`` objects
- model_choices: a generic foreign key to a model which defines the choices for the formfield
- additional_validators: a set of custom defined field validators

Model Choices
~~~~~~~~~~~~~

To define a custom model for field choices the model will need to have an items related name which points to an enum items model containing key and value fields. ::

from django.db import models

class Enum(models.Model):
title = models.CharField(max_length=100)

class EnumItem(models.Model):
enum = models.ForeignKey(Enum, related_name="items")
value = models.CharField(max_length=100)
label = models.CharField(max_length=100)

Actions
~~~~~~~

FormFactory come with some predefined actions:
- store_data: stores the submitted date to a key/value store_data. Requires no ``ActionParam``
- send_email: sends the data via email. Requires the following ``ActionParam``
- from_email_field: mapping to the form field that the email will be sent from
- to_email_field: mapping to the form field that the email will be sent to
- subject_field: mapping to the form field that will be used for the email subject
- login: logs a user in. Requires the following ``ActionParam``
- username_field: mapping to the form field where the username will be completed.
- password_field: mapping to the form field where the username will be completed.
- file_upload: handles uploading files to a predefined path. Requires the following ``ActionParam``
- upload_path_field: mapping to the form field where the upload path has been set.

Custom actions can be added by creating a function in <yourapp or project>/formfactoryapp/actions.py. For example::

from formfactory import actions

@actions.register
def my_custom_action(form_instance, **kwargs):
# do some stuff

Validation
~~~~~~~~~~

Custom validators can be added by creating a function in <yourapp or project>/formfactoryapp/validators.py. For example::

from formfactory import validators

@validators.register
def my_custom_validator(value):
if not condition:
raise ValidationError("Failed")
return True
Authors
=======

Praekelt Consulting
-------------------
* Jonathan Bydendyk
* Phala Ramonyai

Changelog
=========

0.1
---
#. Initial release.