Form Customisation

Currently we have defined two different types of forms, one which just enables saving the submission and one to additionally email the results of the submission.

Custom form model

You can easily add your own all you have to do is create a model that inherits from wagtailstreamforms.models.BaseForm add any additional fields or properties and this will be added to the cms admin area.

Example:

from wagtailstreamforms.models import BaseForm

class CustomForm(BaseForm):

    def process_form_submission(self, form):
        super(CustomForm, self).process_form_submission(form) # handles the submission saving
        # do your own stuff here

Custom form submission model

If you need to save additional data, you can use a custom form submission model. To do this, you need to:

  • Define a model that extends wagtailstreamforms.models.AbstractFormSubmission.
  • Override the get_submission_class and process_form_submission methods in your form model.

Example:

import json

from django.core.serializers.json import DjangoJSONEncoder
from django.db import models
from django.utils.translation import ugettext_lazy as _

from wagtail.wagtailcore.models import Page
from wagtailstreamforms.models import AbstractFormSubmission, BaseForm


class CustomForm(BaseForm):
    """ A form that saves the current user and page. """

    def get_data_fields(self):
        data_fields = super(ExampleForm, self).get_data_fields()
        data_fields += [
            ('user', _('User')),
            ('page', _('Page'))
        ]
        return data_fields

    def get_submission_class(self):
        return CustomFormSubmission

    def process_form_submission(self, form):
        if self.store_submission:
            self.get_submission_class().objects.create(
                form_data=json.dumps(form.cleaned_data, cls=DjangoJSONEncoder),
                form=self,
                page=form.page,
                user=form.user if not form.user.is_anonymous() else None
            )


class CustomFormSubmission(AbstractFormSubmission):
    user = models.ForeignKey(settings.AUTH_USER_MODEL, null=True, blank=True)
    page = models.ForeignKey(Page)

    def get_data(self):
        form_data = super(CustomFormSubmission, self).get_data()
        form_data.update({
            'page': self.page,
            'user': self.user
        })
        return form_data

Note

Its important to note here that the form.page and form.user seen above are passed in via the wagtailstreamforms.models.StreamFormPageMixin which is for forms that post to their own page.

If you want to use a different method of saving the form and you require these you will need to pass them in yourself.

Example usage cam be seen in the mixins serve method here.

Reference

class wagtailstreamforms.models.BaseForm(*args, **kwargs)

A form base class, any form should inherit from this.

get_data_fields()

Returns a list of tuples with (field_name, field_label).

get_form_fields()

Form expects form_fields to be declared. If you want to change backwards relation name, you need to override this method.

get_submission_class()

Returns submission class.

You can override this method to provide custom submission class. Your class must be inherited from AbstractFormSubmission.

process_form_submission(form)

Accepts form instance with submitted data. Creates submission instance if self.store_submission = True.

You can override this method if you want to have custom creation logic. For example, you want to additionally send an email.

class wagtailstreamforms.models.BasicForm(*args, **kwargs)

A basic form.

class wagtailstreamforms.models.EmailForm(*args, **kwargs)

A form that sends and email.

class wagtailstreamforms.models.AbstractFormSubmission(*args, **kwargs)

Data for a form submission.

You can create custom submission model based on this abstract model. For example, if you need to save additional data or a reference to a user.

get_data()

Returns dict with form data.

You can override this method to add additional data.

class wagtailstreamforms.models.FormSubmission(*args, **kwargs)

Data for a Form submission.