Reviews rate options configurable on score fields (#5024)

By default nothing changes.

Setting the new optional `REVIEW_RATE_CHOICES` implementors can change
labels and more importantly disable rate options.

You could change the labels before via translations but there was no way
to disable options.

By setting `REVIEW_RATE_CHOICES = {99: None}` in locale.py or setting
REVIEW_RATE_CHOICES='{"99": null}' in .env will disable the NA option.

Author: frjo

docs/setup/administrators/configuration.md

@@ -213,6 +213,14 @@ Show the total (sum) of a review's scored answers instead of the average of them
 
 ----
 
+Change the labels of, or disable, review score choices. A JSON object keyed by score value (0-5 and 99 for "n/a - choose not to answer"). A string sets a new label, `null`, `false` or `""` disables the choice. If the n/a choice is disabled, score fields start out empty ("---------") instead of at n/a, so in required score fields reviewers have to pick a score. An optional score field left empty still counts as n/a. Existing reviews that used a disabled choice still show its label. Labels set here are not translated.
+
+Example: `REVIEW_RATE_CHOICES='{"0": null, "3": "3. Okay", "99": "n/a"}'`
+
+    REVIEW_RATE_CHOICES = env.json('REVIEW_RATE_CHOICES', {})
+
+----
+
 If automatic e-mails should be sent out to reviewers when submissions are ready for review.
 
     SEND_READY_FOR_REVIEW = env.bool('SEND_READY_FOR_REVIEW', True)

hypha/apply/review/blocks.py

@@ -2,6 +2,7 @@
 
 from django import forms
 from django.conf import settings
+from django.db.models import BLANK_CHOICE_DASH
 from django.utils.safestring import mark_safe
 from django.utils.translation import gettext_lazy as _
 from wagtail.blocks import RichTextBlock
@@ -69,7 +70,8 @@ class ScoreFieldWithoutTextBlock(OptionalFormFieldBlock):
     This block modifies RATE_CHOICES to have empty string('') in place of NA
     for text value `n/a - choose not to answer` as it helps to render this value
     as default to the forms and also when this field is
-    required it automatically handles validation on empty string.
+    required it automatically handles validation on empty string. If NA is
+    disabled an empty choice is added first instead.
     """
 
     name = "score without text"
@@ -87,8 +89,7 @@ def get_field_kwargs(self, struct_value):
     def render(self, value, context=None):
         data = context.get("data", None)
         if data:
-            choices = dict(self.get_choices(RATE_CHOICES))
-            context["data"] = choices[int(data)]
+            context["data"] = RATE_CHOICES_DICT.get(int(data), RATE_CHOICE_NA)
         else:
             context["data"] = ""
 
@@ -98,9 +99,11 @@ def get_choices(self, choices):
         """
         Replace 'NA' option with an empty string choice.
         """
-        rate_choices = list(choices)
-        rate_choices.pop(-1)
-        rate_choices.append(("", _("n/a - choose not to answer")))
+        rate_choices = [choice for choice in choices if choice[0] != NA]
+        if len(rate_choices) < len(choices):
+            rate_choices.append(("", RATE_CHOICE_NA))
+        else:
+            rate_choices = BLANK_CHOICE_DASH + rate_choices
         return tuple(rate_choices)
 
 

hypha/apply/review/fields.py

@@ -1,4 +1,5 @@
 from django import forms
+from django.db.models import BLANK_CHOICE_DASH
 from django.forms import widgets
 from django.utils.safestring import mark_safe
 from tinymce.widgets import TinyMCE
@@ -7,11 +8,23 @@
 from hypha.apply.utils.options import MCE_ATTRIBUTES_SHORT
 
 
+def get_score_choices():
+    """
+    The NA choice is the default. If it is disabled, add an empty choice
+    in its place so no score is preselected.
+    """
+    if NA in dict(RATE_CHOICES):
+        return RATE_CHOICES
+    return tuple(BLANK_CHOICE_DASH) + RATE_CHOICES
+
+
 class ScoredAnswerWidget(forms.MultiWidget):
     def __init__(self, attrs=None):
         _widgets = (
             TinyMCE(attrs=attrs, mce_attrs=MCE_ATTRIBUTES_SHORT),
-            widgets.Select(attrs={"data-score-field": "true"}, choices=RATE_CHOICES),
+            widgets.Select(
+                attrs={"data-score-field": "true"}, choices=get_score_choices()
+            ),
         )
         super().__init__(_widgets, attrs)
 
@@ -42,13 +55,15 @@ class ScoredAnswerField(forms.MultiValueField):
     def __init__(self, *args, **kwargs):
         fields = (
             forms.CharField(),
-            forms.ChoiceField(choices=RATE_CHOICES),
+            forms.ChoiceField(choices=get_score_choices()),
         )
 
         super().__init__(*args, **kwargs, fields=fields)
 
     def compress(self, data_list):
         if data_list:
-            return [data_list[0], int(data_list[1])]
+            # An empty score is only possible when NA is disabled.
+            score = data_list[1]
+            return [data_list[0], int(score) if score != "" else NA]
         else:
             return ["", NA]

hypha/apply/review/options.py

@@ -1,8 +1,9 @@
+from django.conf import settings
 from django.utils.translation import gettext_lazy as _
 
 NA = 99
 
-RATE_CHOICES = (
+DEFAULT_RATE_CHOICES = (
     (0, _("0. Need more info")),
     (1, _("1. Poor")),
     (2, _("2. Not so good")),
@@ -12,7 +13,33 @@
     (NA, _("n/a - choose not to answer")),
 )
 
-RATE_CHOICES_DICT = dict(RATE_CHOICES)
+
+def get_rate_choices():
+    """
+    Apply the REVIEW_RATE_CHOICES setting to DEFAULT_RATE_CHOICES.
+
+    The setting maps a score value (int or str) to a new label, or to a falsy
+    value to disable that choice.
+
+    Returns ``(choices, labels)`` where ``labels`` also includes disabled
+    choices, so existing reviews using them can still be displayed.
+    """
+    overrides = {
+        str(key): value
+        for key, value in getattr(settings, "REVIEW_RATE_CHOICES", {}).items()
+    }
+    choices = []
+    labels = {}
+    for value, default_label in DEFAULT_RATE_CHOICES:
+        override = overrides.get(str(value), default_label)
+        label = override if isinstance(override, str) and override else default_label
+        labels[value] = label
+        if override:
+            choices.append((value, label))
+    return tuple(choices), labels
+
+
+RATE_CHOICES, RATE_CHOICES_DICT = get_rate_choices()
 RATE_CHOICE_NA = RATE_CHOICES_DICT[NA]
 
 NO = 0

hypha/settings/base.py

@@ -220,6 +220,12 @@
 # them, wherever a review score is shown.
 REVIEW_SCORE_SHOW_TOTAL = env.bool("REVIEW_SCORE_SHOW_TOTAL", False)
 
+# Override labels of, or disable, review score choices. JSON object keyed by
+# score value; a string sets a new label, null/false/"" disables the choice.
+# Disabling the n/a choice (99) makes reviewers pick a score in required fields.
+# Example: {"0": null, "3": "3. Okay", "99": "n/a"}
+REVIEW_RATE_CHOICES = env.json("REVIEW_RATE_CHOICES", {})
+
 # Require an applicant to view their rendered application before submitting
 SUBMISSION_PREVIEW_REQUIRED = env.bool("SUBMISSION_PREVIEW_REQUIRED", True)