Installing the form designer

Install the package using pip:

$ pip install form-designer

Setting up the form designer

• Add "form_designer" and "admin_ordering" to INSTALLED_APPS.

• Run ./manage.py migrate form_designer

• Go into Django’s admin panel and add one or more forms with the fields you require. Also select at least one action in the configuration options selectbox, most often you’d want to select both the “E-mail” and the “Save form submission” option and fill in one ore more email addresses.

Choices for selection fields are split on , or alternatively |; use pipe character when individual choices need to contain commas.

If you’re using the form designer with FeinCMS, the content type can be imported from form_designer.contents.FormContent. Otherwise, your code should use the following methods (the code would probably reside in a view):

# Somehow fetch the form_designer.models.Form instance:
instance = get_object_or_404()

# Build the form class:
form_class = instance.form_class()

# Standard form processing:
if request.method == "POST":
    form = form_class(request.POST)

    if form.is_valid():
        # Do what you want, or run the configured processors:
        result = instance.process(form, request)

        # Maybe there's something useful in here:
        pprint(result)

        return HttpResponseRedirect("thanks/")
else:
    form = form_class()

return render(request, "form.html", {"form": form})

Adding custom actions

Custom actions can be added by appending them to Form.CONFIG_OPTIONS:

from form_designer.models import Form

def do_thing(model_instance, form_instance, request, config, **kwargs):
    pass

def do_validate(form_instance, data):
    pass

Form.CONFIG_OPTIONS.append(
    (
        "do_thing",
        {
            "title": _("Do a thing"),
            "form_fields": lambda form: [
                ("optional_form_field", forms.CharField(
                    label=_("Optional form field"),
                    required=False,
                    # validators...
                    # help_text...
                )),
            ],
            "process": do_thing,
            "validate": do_validate,
        },
    )
)

The interesting part is the do_thing callable. It currently receives four arguments, however you should also accept **kwargs to support additional arguments added in the future:

• model_instance: The Form model instance

• form_instance: The dynamically generated form instance

• request: The current HTTP request

• config: The config options (keys and values defined through form_fields; for example the email action defines an email char field, and accesses its value using config["email"]).

ReCaptcha

To enable ReCaptcha install django-recaptcha and add django_recaptcha to your INSTALLED_APPS. This will automatically add a ReCaptcha field to the form designer. For everything else read through the django-recaptcha readme.

reCAPTCHA keys only work with either v2 or v3. Both field types are offered by default; set FORM_DESIGNER_RECAPTCHA_VERSION to "v2" or "v3" to only offer the one matching your keys:

FORM_DESIGNER_RECAPTCHA_VERSION = "v3"

Existing form fields using the other field type will crash, so change them first.

Name the field captcha to omit it from submission data, see Omitted fields.

Simple Captcha

To enable django-simple-captcha install django-simple-captcha and add captcha to your INSTALLED_APPS as described in the documentation for django-simple-captcha. This will automatically add a “Simple Captcha” field to the form designer field types.

Name the field captcha to omit it from submission data, see Omitted fields.

Omitted fields

Fields matching any of the glob patterns in FORM_DESIGNER_OMIT_FIELDS are left out of the submission data and the XLSX export. The default omits captcha and fields starting with _:

FORM_DESIGNER_OMIT_FIELDS = ("captcha", "_*")

Set it to () to include all fields, as in previous versions.

Email action

The email action sends submissions to a comma separated list of addresses. The subject defaults to the form title, but can be set in the action config. %(fieldname)s placeholders are replaced with submitted values (unknown fields become empty), other % signs are kept as-is.

For testing and staging setups, set FORCE_MAIL_RECIPIENT in settings.py to an address to send all submission mails there instead.

FORCE_MAIL_RECIPIENT = "test@nowhere.example"

Override field types

Define FORM_DESIGNER_FIELD_TYPES in your settings file like:

FORM_DESIGNER_FIELD_TYPES = "your_project.form_designer_config.FIELD_TYPES"

In your_project.form_designer_config.py something like:

from django import forms
from django.utils.translation import gettext_lazy as _

FIELD_TYPES = [
    {"type": "text", "verbose_name": _("text"), "field": forms.CharField},
    {"type": "email", "verbose_name": _("email address"), "field": forms.EmailField},
]

Visit these sites for more information

• form_designer: https://github.com/feincms/form_designer

• FeinCMS: https://feincms-django-cms.readthedocs.io/

• feincms3: https://feincms3.readthedocs.io/