Form Builder

Form builder is a collection of tools built on top of Page Builder that help with the creation of HTML forms.

To enable Form Builder, add widgy.contrib.form_builder to your INSTALLED_APPS.


Form builder depends on the following packages:

  • django-widgy[page_builder]
  • django-extensions
  • html2text
  • phonenumbers

You can install them manually, or you can install them using the django-widgy package:

$ pip install django-widgy[page_builder,form_builder]

Success Handlers

When a user submits a Form, the Form will loop through all of the success handler widgets to do the things that you would normally put in the form_valid method of a django.views.generic.FormView, for example. Form Builder provides a couple of built-in success handlers that do things like saving the data, sending emails, or submitting to Salesforce.


class widgy.contrib.form_builder.models.Form

This widget corresponds to the HTML <form> tag. It acts as a container and also can be used to construct a Django Form class.


Returns a Django Form class based on the FormField widgets inside the form.

class widgy.contrib.form_builder.models.Uncaptcha
class widgy.contrib.form_builder.models.FormField

FormField is an abstract base class for the following widgets. Each FormField has the following fields which correspond to the same attributes on django.forms.fields.Field.


Corresponds with the HTML <label> tag. This is the text that will go inside the label.


Indicates whether or not this field is required. Defaults to True.


A TextField for outputting help text.

class widgy.contrib.form_builder.models.FormInput

This is a widget for all simple <input> types. It supports the following input types: text, number, email, tel, checkbox, date. Respectively they correspond with the following Django formfields: CharField, IntegerField, EmailField, PhoneNumberField, BooleanField, DateField.

class widgy.contrib.form_builder.models.Textarea
class widgy.contrib.form_builder.models.ChoiceField
class widgy.contrib.form_builder.models.MultipleChoiceField

Owner Contract

For custom Widgy owners, Form Builder needs to have a view to use for handling form submissions.

  1. Each widgy owner should implement a get_form_action_url(form, widgy_context) method that returns a URL that points to a view (see step 2).
  2. Create a view to handle form submissions for each owner. Form Builder provides the class-based views mixin, HandleFormMixin, to make this easier.


class widgy.contrib.form_builder.views.HandleFormMixin

An abstract view mixin for handling form_builder.Form submissions. It inherits from django.views.generic.edit.FormMixin.

It should be registered with a URL similar to the following.

url('^form/(?P<form_node_pk>[^/]*)/$', 'your_view')

HandleFormMixin does not implement a GET method, so your subclass should handle that. Here is an example of a fully functioning implementation:

from django.views.generic import DetailView
from widgy.contrib.form_builder.views import HandleFormMixin

class EventDetailView(HandleFormMixin, DetailView):
    model = Event

    def post(self, *args, **kwargs):
        self.object = self.get_object()
        return super(EventDetailView, self).post(*args, **kwargs)

widgy.contrib.widgy_mezzanine.views.HandleFormView provides an even more robust example implementation.