diff --git a/README.md b/README.md index 11d07a0..5b8a75f 100644 --- a/README.md +++ b/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` diff --git a/tbxforms/helper.py b/tbxforms/helper.py index 5246e2c..b609231 100644 --- a/tbxforms/helper.py +++ b/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 diff --git a/tests/layout/__snapshots__/test_checkboxes/test_required_field_highlighting_disabled_per_form.html b/tests/layout/__snapshots__/test_checkboxes/test_required_field_highlighting_disabled_per_form.html new file mode 100644 index 0000000..77c2eeb --- /dev/null +++ b/tests/layout/__snapshots__/test_checkboxes/test_required_field_highlighting_disabled_per_form.html @@ -0,0 +1,37 @@ +
+
+
+ + How would you like to be contacted? + (optional) + +

Select all options that are relevant to you.

+
+
+ + +
+
+ + +
+
+ + +
+
+
+
+
diff --git a/tests/layout/__snapshots__/test_checkboxes/test_required_field_highlighting_enabled_per_form.html b/tests/layout/__snapshots__/test_checkboxes/test_required_field_highlighting_enabled_per_form.html new file mode 100644 index 0000000..d337b55 --- /dev/null +++ b/tests/layout/__snapshots__/test_checkboxes/test_required_field_highlighting_enabled_per_form.html @@ -0,0 +1,37 @@ +
+
+
+ + How would you like to be contacted? + * + +

Select all options that are relevant to you.

+
+
+ + +
+
+ + +
+
+ + +
+
+
+
+
diff --git a/tests/layout/test_checkboxes.py b/tests/layout/test_checkboxes.py index 41ce5d3..9438d66 100644 --- a/tests/layout/test_checkboxes.py +++ b/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