Dynamic django form builder.
Project description
Django Form Factory
Dynamic django form builder.
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)
Dependencies
FormFactory makes use of the python markdown package as well as djano-simplemde. The latest tested version are pinned within formfactory/tests/requirements/<django_version>.txt
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. Supports adding none Django fields: ("<module_for_field>", "<display_name>") eg. ("formfactory.fields.ParagraphField", "ParagraphField")
- FORMFACTORY[“widget-types”]
Control the form widget types that can be selected in Admin. Supports adding none Django widgets: ("<module_for_widget>", "<display_name>") eg. ("formfactory.widgets.ParagraphWidget", "ParagraphWidget")
Widgets and Fields
FormFactory ships with a ParagraphField and ParagraphWidget combo. The intended use for these is to allow copy to be added in between fields. Allows for the same base templates to be used in most cases.
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. As well as formfactory/inclusion_tags/form_detail.html and formfactory/inclusion_tags/form_detail_<form-slug>.html for the inclusion tags.
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
ajax_post: Flag that enables JS ajax posting on the default formfactory templates, or to be used as a hook when overriding templates.
- 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 Forms 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 FormFieldGroups 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
Changelog
0.2.3
Fix defaut None placeholder.
0.2.2
Fix setup.py syntax.
0.2.1
Added ParagraphField and ParagraphWidget.
Added Paragraph markdown field on FormField model, for usage alongside field and widget.
Added support for Fields and Widgets outside just base Django’s.
Cater for order_by issue in Django 1.9 and 1.9.1.
Data migration for field_type and widget fields on FormField.
Add missing migrations.
0.2
Ajax form posting added.
0.1
Initial release.
Project details
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for django_formfactory-0.2.3-py2.7.egg
Algorithm | Hash digest | |
---|---|---|
SHA256 | 599ebfc7da930eef106a2e961e9b5911beccb4321d6e2ca4f9dc94787c3af6ea |
|
MD5 | 609449f84bd5bc92bfe70670a1c79948 |
|
BLAKE2b-256 | 4ce24158b681912eda82058e24d023553b9ac19b1c246dab2a02bcc3a97efb74 |