Allow per-form override of settings.TBXFORMS_HIGHLIGHT_REQUIRED_FIELDS

README.md

@@ -197,6 +197,7 @@ allows you to alter the rendering behaviour of forms.
 Every form that inherits from `TbxFormsMixin` (i.e. every form within `tbxforms`)
 will have a `FormHelper` with the following default attributes:
 
+-   `highlight_required_fields`: see [later section on highlighting required fields](#highlight-required-fields-instead-of-optional-ones)
 -   `html5_required = True`
 -   `label_size = Size.MEDIUM`
 -   `legend_size = Size.MEDIUM`
@@ -397,6 +398,21 @@ recommended by GDS.
 If `TBXFORMS_HIGHLIGHT_REQUIRED_FIELDS=True`, required fields will have an
 asterisk appended to their labels and optional fields will not be highlighted.
 
+This setting can be changed on a per-form basis by setting the form helper's
+`highlight_required_fields` attribute:
+
+```python
+from django import forms
+from tbxforms.forms import TbxFormsMixin
+
+
+class ExampleForm(TbxFormsMixin, forms.Form):
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        # Highlight required fields regardless of settings.TBXFORMS_HIGHLIGHT_REQUIRED_FIELDS
+        self.helper.highlight_required_fields = True
+```
+
 You can also style these markers by targeting these CSS classes:
 
 -   `.tbxforms-field_marker--required`

tbxforms/helper.py

@@ -16,6 +16,11 @@ class FormHelper(crispy_forms_helper.FormHelper):
     adding the following attributes to control how the form is rendered.
 
     Attributes:
+        highlight_required_fields (:obj:`bool`, optional): whether to highlight
+            required fields or optional fields. If not set on the form, the
+            `TBXFORMS_HIGHLIGHT_REQUIRED_FIELDS` setting will be used, falling
+            to `False` if that setting is not set.
+
         label_size (:obj:`str`, optional): set the default size used for all
             field labels. The default value of None renders labels with the
             same font size as body text. To change the font size and weight
@@ -55,6 +60,7 @@ def __init__(self, *args, **kwargs):
 
     """
 
+    highlight_required_fields = None
     label_size = ""
     legend_size = ""
     show_error_summary = True
@@ -76,9 +82,14 @@ def render_layout(self, form, context, template_pack=TEMPLATE_PACK):
         if self.legend_size:
             context["legend_size"] = Size.for_legend(self.legend_size)
 
-        context["highlight_required_fields"] = getattr(
-            settings, "TBXFORMS_HIGHLIGHT_REQUIRED_FIELDS", False
-        )
+        if self.highlight_required_fields is not None:
+            context["highlight_required_fields"] = (
+                self.highlight_required_fields
+            )
+        else:
+            context["highlight_required_fields"] = getattr(
+                settings, "TBXFORMS_HIGHLIGHT_REQUIRED_FIELDS", False
+            )
 
         return super().render_layout(
             form, context, template_pack=template_pack

tests/layout/__snapshots__/test_checkboxes/test_required_field_highlighting_disabled_per_form.html

@@ -0,0 +1,37 @@
+<form class="tbxforms" method="post">
+    <div id="div_id_method" class="tbxforms-form-group">
+        <fieldset class="tbxforms-fieldset"  aria-describedby="id_method_hint">
+            <legend class="tbxforms-fieldset__legend tbxforms-fieldset__legend--m">
+                How would you like to be contacted?
+                <span class="tbxforms-field_marker--optional">(optional)</span>
+            </legend>
+            <p id="id_method_hint" class="tbxforms-hint">Select all options that are relevant to you.</p>
+            <div class="tbxforms-checkboxes">
+                <div class="tbxforms-checkboxes__item">
+                    <input type="checkbox"
+                           name="method"
+                           class="tbxforms-checkboxes__input"
+                           id="id_method_1"
+                           value="email" />
+                    <label class="tbxforms-label tbxforms-checkboxes__label" for="id_method_1">Email</label>
+                </div>
+                <div class="tbxforms-checkboxes__item">
+                    <input type="checkbox"
+                           name="method"
+                           class="tbxforms-checkboxes__input"
+                           id="id_method_2"
+                           value="phone" />
+                    <label class="tbxforms-label tbxforms-checkboxes__label" for="id_method_2">Phone</label>
+                </div>
+                <div class="tbxforms-checkboxes__item">
+                    <input type="checkbox"
+                           name="method"
+                           class="tbxforms-checkboxes__input"
+                           id="id_method_3"
+                           value="text" />
+                    <label class="tbxforms-label tbxforms-checkboxes__label" for="id_method_3">Text message</label>
+                </div>
+            </div>
+        </fieldset>
+    </div>
+</form>

tests/layout/__snapshots__/test_checkboxes/test_required_field_highlighting_enabled_per_form.html

@@ -0,0 +1,37 @@
+<form class="tbxforms" method="post">
+    <div id="div_id_method" class="tbxforms-form-group">
+        <fieldset class="tbxforms-fieldset"  aria-describedby="id_method_hint">
+            <legend class="tbxforms-fieldset__legend tbxforms-fieldset__legend--m">
+                How would you like to be contacted?
+                <span class="tbxforms-field_marker--required" title="(required)">*</span>
+            </legend>
+            <p id="id_method_hint" class="tbxforms-hint">Select all options that are relevant to you.</p>
+            <div class="tbxforms-checkboxes">
+                <div class="tbxforms-checkboxes__item">
+                    <input type="checkbox"
+                           name="method"
+                           class="tbxforms-checkboxes__input"
+                           id="id_method_1"
+                           value="email" />
+                    <label class="tbxforms-label tbxforms-checkboxes__label" for="id_method_1">Email</label>
+                </div>
+                <div class="tbxforms-checkboxes__item">
+                    <input type="checkbox"
+                           name="method"
+                           class="tbxforms-checkboxes__input"
+                           id="id_method_2"
+                           value="phone" />
+                    <label class="tbxforms-label tbxforms-checkboxes__label" for="id_method_2">Phone</label>
+                </div>
+                <div class="tbxforms-checkboxes__item">
+                    <input type="checkbox"
+                           name="method"
+                           class="tbxforms-checkboxes__input"
+                           id="id_method_3"
+                           value="text" />
+                    <label class="tbxforms-label tbxforms-checkboxes__label" for="id_method_3">Text message</label>
+                </div>
+            </div>
+        </fieldset>
+    </div>
+</form>

tests/layout/test_checkboxes.py

@@ -97,3 +97,21 @@ def test_required_field_highlighting(snapshot_html):
     """
     form = CheckboxesForm()
     assert render_form(form) == snapshot_html
+
+
+@override_settings(TBXFORMS_HIGHLIGHT_REQUIRED_FIELDS=True)
+def test_required_field_highlighting_disabled_per_form(snapshot_html):
+    """
+    Ensure that required field highlighting can be turned off per-form.
+    """
+    form = CheckboxesForm()
+    form.helper.highlight_required_fields = False
+    form.fields["method"].required = False
+    assert render_form(form) == snapshot_html
+
+
+@override_settings(TBXFORMS_HIGHLIGHT_REQUIRED_FIELDS=False)
+def test_required_field_highlighting_enabled_per_form(snapshot_html):
+    form = CheckboxesForm()
+    form.helper.highlight_required_fields = True
+    assert render_form(form) == snapshot_html