Allow subclassing of form builder (#15)

By following wagtail convention of defining `form_builder` at the class level instead of hardcoding in in `init`, it allows the end-user to provide his own subclass.

Author: loicteixeira

CHANGELOG.rst

@@ -5,6 +5,7 @@ Unreleased
 ------------------
 #. Add Wagtail 2.0 compatibility.
 #. Ensure captcha field is properly removed from submission data. (issue #11)
+#. Allow subclassing of the form builder. (issue #7)
 
 0.2 (2016-10-16)
 ------------------

README.rst

@@ -71,7 +71,23 @@ Example
 
 The captcha field can't be added from the admin UI but will appear in your frontend as the last of the form fields.
 
-    For a more thorough example, `Made with Wagtail <http://madewithwagtail.org/>`_ (`github.com/springload/madewithwagtail <https://github.com/springload/madewithwagtail>`_) is an example of an open-source site using this module.
+If you need to customise the behaviour of the form builder, make sure to inherit from ``wagtailcaptcha.forms.WagtailCaptchaFormBuilder`` instead of Wagtail's default form builder, then declare it as usual on the page model.
+
+.. code-block:: python
+
+    from wagtailcaptcha.forms import WagtailCaptchaFormBuilder
+    from wagtailcaptcha.models import WagtailCaptchaForm
+
+
+    class CustomFormBuilder(WagtailCaptchaFormBuilder):
+        # Some custom behaviour...
+
+
+    class FormPage(WagtailCaptchaForm):
+        form_builder = CustomFormBuilder
+        # The rest of the page definition as usual...
+
+For a more thorough example, `Made with Wagtail <http://madewithwagtail.org/>`_ (`github.com/springload/madewithwagtail <https://github.com/springload/madewithwagtail>`_) is an example of an open-source site using this module.
 
 Development
 -----------

tests/test_models.py

@@ -4,7 +4,13 @@
 
 from django.test import TestCase
 
-from home.models import TestCaptchaEmailFormPage, TestCaptchaFormPage
+from home.forms import CustomCaptchaFormBuilder
+from home.models import (
+    TestCaptchaEmailFormPage,
+    TestCaptchaFormPage,
+    TestCustomFormBuilderCaptchaEmailFormPage,
+    TestCustomFormBuilderCaptchaFormPage,
+)
 from wagtailcaptcha.forms import WagtailCaptchaFormBuilder
 
 try:
@@ -26,11 +32,16 @@ def setUp(self):
 class TestCaptchaEmailFormPageTestCase(CaptchaTestingModeMixin, TestCase):
     fixtures = ['test_data.json']
 
-    def test_captcha_form_builder_is_set(self):
+    def test_default_form_builder_is_set(self):
         page = TestCaptchaEmailFormPage()
 
         self.assertIs(page.form_builder, WagtailCaptchaFormBuilder)
 
+    def test_form_builder_can_be_replaced(self):
+        page = TestCustomFormBuilderCaptchaEmailFormPage()
+
+        self.assertIs(page.form_builder, CustomCaptchaFormBuilder)
+
     def test_captcha_field_is_removed_from_submission_data(self):
         page = TestCaptchaEmailFormPage.objects.get(slug='email-form')
         form_data = dict(self.captcha_form_data, name='Robert')
@@ -48,11 +59,16 @@ def test_captcha_field_is_removed_from_submission_data(self):
 class TestCaptchaFormPageTestCase(CaptchaTestingModeMixin, TestCase):
     fixtures = ['test_data.json']
 
-    def test_captcha_form_builder_is_set(self):
+    def test_default_form_builder_is_set(self):
         page = TestCaptchaFormPage()
 
         self.assertIs(page.form_builder, WagtailCaptchaFormBuilder)
 
+    def test_form_builder_can_be_replaced(self):
+        page = TestCustomFormBuilderCaptchaFormPage()
+
+        self.assertIs(page.form_builder, CustomCaptchaFormBuilder)
+
     def test_captcha_field_is_removed_from_submission_data(self):
         page = TestCaptchaFormPage.objects.get(slug='form')
         form_data = dict(self.captcha_form_data, name='Robert')

tests/testapp/home/forms.py

@@ -0,0 +1,7 @@
+from __future__ import absolute_import, unicode_literals
+
+from wagtailcaptcha.forms import WagtailCaptchaFormBuilder
+
+
+class CustomCaptchaFormBuilder(WagtailCaptchaFormBuilder):
+    pass  # This doesn't implement any new functionality but is needed to test that subclassing is possible.

tests/testapp/home/migrations/0002_custom_form_builder_pages.py

@@ -0,0 +1,85 @@
+# -*- coding: utf-8 -*-
+# Generated by Django 1.11.10 on 2018-02-09 01:04
+from __future__ import unicode_literals
+
+from django.db import migrations, models
+import django.db.models.deletion
+import modelcluster.fields
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ('wagtailcore', '0040_page_draft_title'),
+        ('home', '0001_initial'),
+    ]
+
+    operations = [
+        migrations.CreateModel(
+            name='TestCustomFormBuilderCaptchaEmailFormField',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('sort_order', models.IntegerField(blank=True, editable=False, null=True)),
+                ('label', models.CharField(help_text='The label of the form field', max_length=255, verbose_name='label')),
+                ('field_type', models.CharField(choices=[('singleline', 'Single line text'), ('multiline', 'Multi-line text'), ('email', 'Email'), ('number', 'Number'), ('url', 'URL'), ('checkbox', 'Checkbox'), ('checkboxes', 'Checkboxes'), ('dropdown', 'Drop down'), ('multiselect', 'Multiple select'), ('radio', 'Radio buttons'), ('date', 'Date'), ('datetime', 'Date/time')], max_length=16, verbose_name='field type')),
+                ('required', models.BooleanField(default=True, verbose_name='required')),
+                ('choices', models.TextField(blank=True, help_text='Comma separated list of choices. Only applicable in checkboxes, radio and dropdown.', verbose_name='choices')),
+                ('default_value', models.CharField(blank=True, help_text='Default value. Comma separated values supported for checkboxes.', max_length=255, verbose_name='default value')),
+                ('help_text', models.CharField(blank=True, max_length=255, verbose_name='help text')),
+            ],
+            options={
+                'ordering': ['sort_order'],
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='TestCustomFormBuilderCaptchaEmailFormPage',
+            fields=[
+                ('page_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='wagtailcore.Page')),
+                ('to_address', models.CharField(blank=True, help_text='Optional - form submissions will be emailed to these addresses. Separate multiple addresses by comma.', max_length=255, verbose_name='to address')),
+                ('from_address', models.CharField(blank=True, max_length=255, verbose_name='from address')),
+                ('subject', models.CharField(blank=True, max_length=255, verbose_name='subject')),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('wagtailcore.page',),
+        ),
+        migrations.CreateModel(
+            name='TestCustomFormBuilderCaptchaFormField',
+            fields=[
+                ('id', models.AutoField(auto_created=True, primary_key=True, serialize=False, verbose_name='ID')),
+                ('sort_order', models.IntegerField(blank=True, editable=False, null=True)),
+                ('label', models.CharField(help_text='The label of the form field', max_length=255, verbose_name='label')),
+                ('field_type', models.CharField(choices=[('singleline', 'Single line text'), ('multiline', 'Multi-line text'), ('email', 'Email'), ('number', 'Number'), ('url', 'URL'), ('checkbox', 'Checkbox'), ('checkboxes', 'Checkboxes'), ('dropdown', 'Drop down'), ('multiselect', 'Multiple select'), ('radio', 'Radio buttons'), ('date', 'Date'), ('datetime', 'Date/time')], max_length=16, verbose_name='field type')),
+                ('required', models.BooleanField(default=True, verbose_name='required')),
+                ('choices', models.TextField(blank=True, help_text='Comma separated list of choices. Only applicable in checkboxes, radio and dropdown.', verbose_name='choices')),
+                ('default_value', models.CharField(blank=True, help_text='Default value. Comma separated values supported for checkboxes.', max_length=255, verbose_name='default value')),
+                ('help_text', models.CharField(blank=True, max_length=255, verbose_name='help text')),
+            ],
+            options={
+                'ordering': ['sort_order'],
+                'abstract': False,
+            },
+        ),
+        migrations.CreateModel(
+            name='TestCustomFormBuilderCaptchaFormPage',
+            fields=[
+                ('page_ptr', models.OneToOneField(auto_created=True, on_delete=django.db.models.deletion.CASCADE, parent_link=True, primary_key=True, serialize=False, to='wagtailcore.Page')),
+            ],
+            options={
+                'abstract': False,
+            },
+            bases=('wagtailcore.page',),
+        ),
+        migrations.AddField(
+            model_name='testcustomformbuildercaptchaformfield',
+            name='page',
+            field=modelcluster.fields.ParentalKey(on_delete=django.db.models.deletion.CASCADE, related_name='form_fields', to='home.TestCustomFormBuilderCaptchaFormPage'),
+        ),
+        migrations.AddField(
+            model_name='testcustomformbuildercaptchaemailformfield',
+            name='page',
+            field=modelcluster.fields.ParentalKey(on_delete=django.db.models.deletion.CASCADE, related_name='form_fields', to='home.TestCustomFormBuilderCaptchaEmailFormPage'),
+        ),
+    ]

tests/testapp/home/models.py

@@ -5,6 +5,7 @@
 from modelcluster.fields import ParentalKey
 
 from wagtailcaptcha.models import WagtailCaptchaEmailForm, WagtailCaptchaForm
+from .forms import CustomCaptchaFormBuilder
 
 if wagtail.VERSION >= (2, 0):
     from wagtail.admin.edit_handlers import FieldPanel, FieldRowPanel, InlinePanel, MultiFieldPanel
@@ -39,3 +40,25 @@ class TestCaptchaFormPage(WagtailCaptchaForm):
     content_panels = WagtailCaptchaForm.content_panels + [
         InlinePanel('form_fields', label="Form fields"),
     ]
+
+
+class TestCustomFormBuilderCaptchaEmailFormField(AbstractFormField):
+    page = ParentalKey(
+        'TestCustomFormBuilderCaptchaEmailFormPage',
+        related_name='form_fields',
+        on_delete=models.CASCADE,
+    )
+
+
+class TestCustomFormBuilderCaptchaEmailFormPage(WagtailCaptchaEmailForm):
+    form_builder = CustomCaptchaFormBuilder
+    is_creatable = False  # Don't show in the admin
+
+
+class TestCustomFormBuilderCaptchaFormField(AbstractFormField):
+    page = ParentalKey('TestCustomFormBuilderCaptchaFormPage', related_name='form_fields', on_delete=models.CASCADE)
+
+
+class TestCustomFormBuilderCaptchaFormPage(WagtailCaptchaForm):
+    form_builder = CustomCaptchaFormBuilder
+    is_creatable = False  # Don't show in the admin

wagtailcaptcha/models.py

@@ -12,9 +12,7 @@
 class WagtailCaptchaEmailForm(AbstractEmailForm):
     """Pages implementing a captcha form with email notification should inhert from this"""
 
-    def __init__(self, *args, **kwargs):
-        super(WagtailCaptchaEmailForm, self).__init__(*args, **kwargs)
-        self.form_builder = WagtailCaptchaFormBuilder
+    form_builder = WagtailCaptchaFormBuilder
 
     def process_form_submission(self, form):
         remove_captcha_field(form)
@@ -27,9 +25,7 @@ class Meta:
 class WagtailCaptchaForm(AbstractForm):
     """Pages implementing a captcha form should inhert from this"""
 
-    def __init__(self, *args, **kwargs):
-        super(WagtailCaptchaForm, self).__init__(*args, **kwargs)
-        self.form_builder = WagtailCaptchaFormBuilder
+    form_builder = WagtailCaptchaFormBuilder
 
     def process_form_submission(self, form):
         remove_captcha_field(form)