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
andprocess_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.
-
copy
()¶ Copy this form and its fields.
-
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.
-
specific
¶ Returns the specific form instance.
-
specific_class
¶ Return the class that this form would be if instantiated in its most specific form
-
-
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.