extract subclass to deal with conditional field logic

We need to handle conditional validation in most of our forms, so I want
to create something reusable for this.

Author: MatMoore

manage_breast_screening/nhsuk_forms/forms.py

@@ -0,0 +1,153 @@
+"""
+Helpers to handle conditionally required fields
+"""
+
+from dataclasses import dataclass
+from typing import Any
+
+from django.forms import Form, ValidationError
+
+
+@dataclass
+class ConditionalRequirement:
+    predicate_field: str
+    predicate_field_value: Any
+    conditionally_required_field: str
+
+
+class FieldPredicate:
+    def __init__(self, validator, field_name, field_choices):
+        self.validator = validator
+        self.field_name = field_name
+        self.field_choices = field_choices
+
+    def require_field_with_prefix(self, prefix):
+        for value, _ in self.field_choices:
+            self.validator.require_field_with_value(
+                predicate_field=self.field_name,
+                predicate_field_value=value,
+                conditionally_required_field=f"{prefix}_{value.lower()}",
+            )
+
+
+class FieldValuePredicate:
+    def __init__(self, validator, field, field_value):
+        self.validator = validator
+        self.field = field
+        self.field_value = field_value
+
+    def require_field(self, conditionally_required_field):
+        self.validator.require_field_with_value(
+            predicate_field=self.field,
+            predicate_field_value=self.field_value,
+            conditionally_required_field=conditionally_required_field,
+        )
+
+
+class ConditionalFieldValidator:
+    """
+    Helper class to perform the conditional validation for the FormWithConditionalFields
+    """
+
+    def __init__(self, form):
+        self.conditional_requirements = []
+        self.form = form
+
+    def require_field_with_value(
+        self, conditionally_required_field, predicate_field, predicate_field_value
+    ):
+        """
+        Mark a field as conditionally required if and only if another field (the predicate field)
+        is set to a specific value.
+        If the predicate field is set to the predicate value, this field will require a value.
+        If the predicate field is set to a different value, this field's value will be ignored.
+        """
+        if conditionally_required_field not in self.form.fields:
+            raise ValueError(f"{conditionally_required_field} is not a valid field")
+        if predicate_field not in self.form.fields:
+            raise ValueError(f"{predicate_field} is not a valid field")
+
+        self.conditional_requirements.append(
+            ConditionalRequirement(
+                conditionally_required_field=conditionally_required_field,
+                predicate_field=predicate_field,
+                predicate_field_value=predicate_field_value,
+            )
+        )
+
+        self.form.fields[conditionally_required_field].required = False
+
+    def clean_conditional_fields(self):
+        form = self.form
+        for requirement in self.conditional_requirements:
+            field = requirement.conditionally_required_field
+            predicate_field_value = form.cleaned_data.get(requirement.predicate_field)
+
+            if predicate_field_value == requirement.predicate_field_value:
+                cleaned_value = form.cleaned_data.get(field)
+                if isinstance(cleaned_value, str):
+                    cleaned_value = cleaned_value.strip()
+
+                if not cleaned_value:
+                    form.add_error(
+                        field,
+                        ValidationError(
+                            message=form.fields[field].error_messages["required"],
+                            code="required",
+                        ),
+                    )
+            else:
+                del form.cleaned_data[field]
+
+
+class FormWithConditionalFields(Form):
+    """
+    This form class makes it possible to declare conditional relationships between two fields.
+    E.g. if the user selects a particular value of one field (the predicate field) then
+    another field (the conditional field) should become required.
+
+    Declare the fields normally, then in the `__init__`, after the superclass has been initialised,
+    call `given_field_value().require_field()` or `given_field().require_field_with_prefix()`
+    to declare the relationships.
+    """
+
+    def __init__(self, *args, **kwargs):
+        self.conditional_field_validator = ConditionalFieldValidator(self)
+
+        super().__init__(*args, **kwargs)
+
+    def given_field_value(self, field, field_value):
+        """
+        Mini-DSL to declare conditional field relationships
+
+        e.g. self.given_field_value('foo', 'choice1').require_field('other_details')
+        """
+        return FieldValuePredicate(
+            self.conditional_field_validator, field=field, field_value=field_value
+        )
+
+    def given_field(self, predicate_field):
+        """
+        Mini-DSL to declare conditional field relationships
+
+        e.g. self.given_field('foo').require_field_with_prefix('other')
+        """
+        return FieldPredicate(
+            self.conditional_field_validator,
+            field_name=predicate_field,
+            field_choices=self.fields[predicate_field].choices,
+        )
+
+    def clean_conditional_fields(self):
+        """
+        Apply the validation and blank out any conditional fields that do not have their predicate met.
+        This can happen when the user selects one option, fills out the conditional field, and then changes
+        to a different option.
+        """
+        return self.conditional_field_validator.clean_conditional_fields()
+
+    def clean(self):
+        cleaned_data = super().clean()
+        self.clean_conditional_fields()
+
+        return cleaned_data

manage_breast_screening/nhsuk_forms/tests/test_forms.py

@@ -0,0 +1,101 @@
+import pytest
+from django.forms import CharField, ChoiceField
+
+from manage_breast_screening.nhsuk_forms.forms import FormWithConditionalFields
+
+
+class TestFormWithConditionalFields:
+    def test_does_nothing_if_no_fields_declared(self):
+        class MyForm(FormWithConditionalFields):
+            foo = CharField()
+
+        form = MyForm({"foo": "bar"})
+        assert form.is_valid()
+        assert form.cleaned_data["foo"] == "bar"
+
+    @pytest.fixture
+    def FormWithSimpleConditional(self):
+        class MyForm(FormWithConditionalFields):
+            foo = ChoiceField(choices=(("a", "a"), ("b", "b")))
+            bar = CharField()
+
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, **kwargs)
+
+                self.given_field_value("foo", "a").require_field("bar")
+
+        return MyForm
+
+    @pytest.fixture
+    def FormWithConditionalFieldsPerValue(self):
+        class MyForm(FormWithConditionalFields):
+            foo = ChoiceField(choices=(("a", "a"), ("b", "b")))
+            other_a = CharField()
+            other_b = CharField()
+
+            def __init__(self, *args, **kwargs):
+                super().__init__(*args, **kwargs)
+
+                self.given_field("foo").require_field_with_prefix("other")
+
+        return MyForm
+
+    def test_simple_conditional_condition_not_met(self, FormWithSimpleConditional):
+        form = FormWithSimpleConditional({"foo": "b"})
+        assert form.is_valid()
+        assert form.cleaned_data["foo"] == "b"
+
+    def test_simple_conditional_condition_met(self, FormWithSimpleConditional):
+        form = FormWithSimpleConditional({"foo": "a", "bar": "abc"})
+        assert form.is_valid()
+        assert form.cleaned_data["foo"] == "a"
+        assert form.cleaned_data["bar"] == "abc"
+
+    def test_simple_conditional_condition_missing_value(
+        self, FormWithSimpleConditional
+    ):
+        form = FormWithSimpleConditional({"foo": "a"})
+        assert not form.is_valid()
+        assert form.errors == {"bar": ["This field is required."]}
+
+    def test_simple_conditional_with_unused_value(self, FormWithSimpleConditional):
+        form = FormWithSimpleConditional({"foo": "b", "bar": "abc"})
+        assert form.is_valid()
+        assert form.cleaned_data["foo"] == "b"
+        assert not form.cleaned_data.get("bar")
+
+    def test_simnple_conditional_predicate_missing(self, FormWithSimpleConditional):
+        form = FormWithSimpleConditional({})
+        assert not form.is_valid()
+        assert form.errors == {"foo": ["This field is required."]}
+
+    def test_per_value_conditional_missing_value(
+        self, FormWithConditionalFieldsPerValue
+    ):
+        form = FormWithConditionalFieldsPerValue({"foo": "b"})
+        assert not form.is_valid()
+        assert form.errors == {"other_b": ["This field is required."]}
+
+    def test_per_value_conditional_provided_value(
+        self, FormWithConditionalFieldsPerValue
+    ):
+        form = FormWithConditionalFieldsPerValue({"foo": "a", "other_a": "abc"})
+        assert form.is_valid()
+        assert form.cleaned_data["foo"] == "a"
+        assert form.cleaned_data["other_a"] == "abc"
+
+    def test_per_value_conditional_with_unused_value(
+        self, FormWithConditionalFieldsPerValue
+    ):
+        form = FormWithConditionalFieldsPerValue(
+            {"foo": "b", "other_a": "abc", "other_b": "def"}
+        )
+        assert form.is_valid()
+        assert form.cleaned_data["foo"] == "b"
+        assert form.cleaned_data["other_b"] == "def"
+        assert not form.cleaned_data.get("other_a")
+
+    def test_per_value_predicate_missing(self, FormWithConditionalFieldsPerValue):
+        form = FormWithConditionalFieldsPerValue({})
+        assert not form.is_valid()
+        assert form.errors == {"foo": ["This field is required."]}