feat: third/fourth layout fix, notify_submitter migration (v0.37.15)

matteius · matteius · commit b9c7038e3d6a · 2026-03-27T15:27:19.000-04:00
forms.py:
- Fix third/fourth width fields rendering on separate lines by grouping
  consecutive same-width fields into a shared Row (up to 3 for third,
  4 for fourth) -- same pattern already used for half-width fields

models.py (WorkflowNotification):
- Add notify_submitter BooleanField(default=False) so the submitter
  can be targeted as a recipient from the new notification system
- Update clean() to validate at least one recipient source is set
- Update __str__ to include submitter in recipient description

migrations:
- 0066: schema migration adding notify_submitter column
- 0067: data migration converting legacy notify_on_* flags to
  WorkflowNotification rows with notify_submitter=True and
  static_emails from additional_notify_emails

tasks.py:
- _collect_notification_recipients: add submission param; prepend
  submitter email when notif.notify_submitter is True
- send_workflow_definition_notifications: pass submission= to recipient helper
- 4 legacy tasks: early-return guard when notify_submitter row exists

admin.py:
- WorkflowNotificationInline + Admin: add notify_submitter field
- Legacy notifications fieldset: labelled Deprecated with migration guidance

Bump 0.37.14 to 0.37.15
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,20 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.37.15] - 2026-03-27
+
+### Fixed
+- **`third`/`fourth` width fields rendering on separate lines** — The `_setup_layout` method now collects consecutive same-width fields into a shared `Row` (up to 3 for `third`/`col-md-4`, up to 4 for `fourth`/`col-md-3`), exactly like the existing `half` grouping logic. Previously each field got its own `Row`, forcing them onto individual lines regardless of width.
+
+### Added
+- **`WorkflowNotification.notify_submitter`** — New boolean field (default `False`). When checked, the submission's submitter email is always included as a recipient alongside any `email_field` or `static_emails`. This is the replacement for the legacy `notify_on_*` flags.
+- **Schema migration `0066`** — Adds `notify_submitter` to `WorkflowNotification`.
+- **Data migration `0067`** — Converts existing `WorkflowDefinition.notify_on_*` flags into `WorkflowNotification` rows with `notify_submitter=True` and `static_emails` copied from `additional_notify_emails`. Idempotent: skips if a matching row already exists.
+- **`_collect_notification_recipients` handles `notify_submitter`** — Passes through a `submission` parameter; prepends `submission.submitter.email` when `notify_submitter=True`.
+- **Legacy tasks defer to `WorkflowNotification`** — `send_rejection_notification`, `send_approval_notification`, `send_submission_notification`, and `send_withdrawal_notification` now check for an existing `WorkflowNotification` row with `notify_submitter=True` for the matching event type. If found, they return early to avoid sending duplicate emails alongside the new system.
+- **Admin updates** — `WorkflowNotificationInline` and `WorkflowNotificationAdmin` both expose `notify_submitter` in fieldsets and list view. The legacy notifications fieldset is now labelled `⚠️ Deprecated` with an explanatory banner directing admins to the new `WorkflowNotification` inline.
+- **`WorkflowNotification.clean()` validation** — Raises `ValidationError` if none of `notify_submitter`, `email_field`, or `static_emails` is set.
+
 ## [0.37.14] - 2026-03-27
 
 ### Fixed
diff --git a/django_forms_workflows/admin.py b/django_forms_workflows/admin.py
@@ -447,8 +447,8 @@ class WorkflowNotificationInline(nested_admin.NestedStackedInline):
             None,
             {
                 "fields": (
-                    ("notification_type", "email_field"),
-                    "static_emails",
+                    ("notification_type", "notify_submitter"),
+                    ("email_field", "static_emails"),
                     "subject_template",
                 )
             },
@@ -1457,18 +1457,18 @@ class WorkflowDefinitionAdmin(nested_admin.NestedModelAdmin):
             },
         ),
         (
-            "Legacy Notifications (submitter + additional emails)",
+            "⚠️ Deprecated — Legacy Notifications (submitter + additional emails)",
             {
                 "classes": ("collapse",),
                 "description": (
-                    "<strong>These toggles control the built-in submitter notification emails</strong> "
-                    "(submission received, approved, rejected, withdrawn). "
-                    "They send one email to the submitter plus any addresses in "
-                    "<em>Additional notify emails</em>.<br><br>"
-                    "For <strong>granular, per-event, per-recipient rules</strong> — "
-                    "e.g. a separate email to an advisor only on approval, or a "
-                    "conditional alert to a department head — use the "
-                    "<strong>Workflow Notifications</strong> inline below instead."
+                    "<strong style='color:#b45309;'>DEPRECATED.</strong> "
+                    "These flags are superseded by the <strong>Workflow Notifications</strong> inline below. "
+                    "A data migration has already converted enabled flags into WorkflowNotification rows "
+                    "with <em>Notify submitter</em> checked — those rows now control submitter emails for this workflow. "
+                    "The legacy flags are skipped automatically whenever a matching WorkflowNotification row exists.<br><br>"
+                    "You can safely leave these enabled for now; they will be removed in a future release. "
+                    "To fully migrate, disable each flag here and confirm that a corresponding "
+                    "Workflow Notification row (with <em>Notify submitter</em> = ✓) is configured below."
                 ),
                 "fields": (
                     (
@@ -1530,12 +1530,13 @@ class WorkflowNotificationAdmin(admin.ModelAdmin):
     list_display = (
         "workflow_form",
         "notification_type",
+        "notify_submitter",
         "email_field",
         "static_emails_truncated",
         "has_conditions",
         "subject_template_truncated",
     )
-    list_filter = ("notification_type", "workflow__form_definition")
+    list_filter = ("notification_type", "notify_submitter", "workflow__form_definition")
     list_select_related = ("workflow__form_definition",)
     search_fields = (
         "workflow__form_definition__name",
@@ -1549,8 +1550,8 @@ class WorkflowNotificationAdmin(admin.ModelAdmin):
             {
                 "fields": (
                     "workflow",
-                    ("notification_type", "email_field"),
-                    "static_emails",
+                    ("notification_type", "notify_submitter"),
+                    ("email_field", "static_emails"),
                     "subject_template",
                 )
             },
diff --git a/django_forms_workflows/forms.py b/django_forms_workflows/forms.py
@@ -211,26 +211,31 @@ def __init__(self, form_definition, user=None, initial_data=None, *args, **kwarg
                         )
                     )
                     i += 1
-            elif field.width == "third":
-                layout_fields.append(
-                    Div(
-                        Row(
-                            Column(Field(field.field_name), css_class="col-md-4"),
-                        ),
-                        css_class=f"field-wrapper field-{field.field_name}",
-                    )
-                )
-                i += 1
-            elif field.width == "fourth":
+            elif field.width in ("third", "fourth"):
+                # Collect consecutive same-width fields (up to 3 for third, 4 for fourth)
+                # into a single Row so they sit side-by-side.
+                col_class = "col-md-4" if field.width == "third" else "col-md-3"
+                max_per_row = 3 if field.width == "third" else 4
+                group = []
+                while (
+                    i < len(fields)
+                    and len(group) < max_per_row
+                    and fields[i].width == field.width
+                    and fields[i].field_type != "section"
+                ):
+                    group.append(fields[i])
+                    i += 1
                 layout_fields.append(
-                    Div(
-                        Row(
-                            Column(Field(field.field_name), css_class="col-md-3"),
-                        ),
-                        css_class=f"field-wrapper field-{field.field_name}",
+                    Row(
+                        *[
+                            Div(
+                                Field(f.field_name),
+                                css_class=f"{col_class} field-wrapper field-{f.field_name}",
+                            )
+                            for f in group
+                        ]
                     )
                 )
-                i += 1
             else:
                 layout_fields.append(
                     Div(
diff --git a/django_forms_workflows/migrations/0066_add_notify_submitter_to_workflownotification.py b/django_forms_workflows/migrations/0066_add_notify_submitter_to_workflownotification.py
@@ -0,0 +1,21 @@
+# Generated by Django 5.2.7 on 2026-03-27 19:22
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        ("django_forms_workflows", "0065_workflownotification"),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="workflownotification",
+            name="notify_submitter",
+            field=models.BooleanField(
+                default=False,
+                help_text="If checked, the person who submitted the form is always included as a recipient. Use this to replace the legacy 'notify on …' flags with a fully-configurable rule.",
+            ),
+        ),
+    ]
diff --git a/django_forms_workflows/migrations/0067_migrate_legacy_notify_flags.py b/django_forms_workflows/migrations/0067_migrate_legacy_notify_flags.py
@@ -0,0 +1,68 @@
+"""
+Data migration: convert legacy notify_on_* flags on WorkflowDefinition into
+granular WorkflowNotification rows with notify_submitter=True.
+
+For each WorkflowDefinition we create up to four WorkflowNotification rows —
+one per enabled legacy flag. Any additional_notify_emails are copied to
+static_emails on the same row so existing CC behaviour is preserved.
+
+Rows are only created if no WorkflowNotification of that type already exists
+for the workflow, keeping the migration idempotent.
+"""
+
+from django.db import migrations
+
+FLAG_MAP = [
+    ("notify_on_submission", "submission_received"),
+    ("notify_on_approval", "approval_notification"),
+    ("notify_on_rejection", "rejection_notification"),
+    ("notify_on_withdrawal", "withdrawal_notification"),
+]
+
+
+def convert_legacy_flags(apps, schema_editor):
+    WorkflowDefinition = apps.get_model("django_forms_workflows", "WorkflowDefinition")
+    WorkflowNotification = apps.get_model("django_forms_workflows", "WorkflowNotification")
+
+    for workflow in WorkflowDefinition.objects.all():
+        static_emails = (workflow.additional_notify_emails or "").strip()
+        existing_types = set(
+            WorkflowNotification.objects.filter(workflow=workflow).values_list(
+                "notification_type", flat=True
+            )
+        )
+
+        for flag_field, notification_type in FLAG_MAP:
+            if not getattr(workflow, flag_field, False):
+                continue
+            if notification_type in existing_types:
+                # Already configured via the new system — skip to avoid duplicates.
+                continue
+            WorkflowNotification.objects.create(
+                workflow=workflow,
+                notification_type=notification_type,
+                notify_submitter=True,
+                static_emails=static_emails,
+            )
+
+
+def reverse_migration(apps, schema_editor):
+    """
+    Reverse: remove WorkflowNotification rows that were created by this migration
+    (identified by notify_submitter=True and no email_field set).
+    We cannot distinguish them from manually-created rows with the same pattern,
+    so we only remove rows that have notify_submitter=True and no email_field.
+    """
+    WorkflowNotification = apps.get_model("django_forms_workflows", "WorkflowNotification")
+    WorkflowNotification.objects.filter(notify_submitter=True, email_field="").delete()
+
+
+class Migration(migrations.Migration):
+    dependencies = [
+        ("django_forms_workflows", "0066_add_notify_submitter_to_workflownotification"),
+    ]
+
+    operations = [
+        migrations.RunPython(convert_legacy_flags, reverse_migration),
+    ]
+
diff --git a/django_forms_workflows/models.py b/django_forms_workflows/models.py
@@ -1039,11 +1039,12 @@ class WorkflowNotification(models.Model):
 
     Recipients are the union of:
 
+    * ``notify_submitter`` — if True, the person who submitted the form is always included.
     * ``email_field`` — slug of the form field whose value is the recipient email
       (resolved from ``form_data`` at send time, varies per submission).
     * ``static_emails`` — comma-separated fixed addresses always included.
 
-    At least one of the two must be provided.
+    At least one of the three must be set.
 
     ``conditions`` (same JSON format as ``WorkflowStage.trigger_conditions``)
     are evaluated against ``form_data`` before sending; leave blank to always send.
@@ -1070,6 +1071,13 @@ class WorkflowNotification(models.Model):
         default="approval_notification",
         help_text="Which workflow event triggers this notification.",
     )
+    notify_submitter = models.BooleanField(
+        default=False,
+        help_text=(
+            "If checked, the person who submitted the form is always included as a recipient. "
+            "Use this to replace the legacy 'notify on …' flags with a fully-configurable rule."
+        ),
+    )
     email_field = models.CharField(
         max_length=200,
         blank=True,
@@ -1112,16 +1120,33 @@ class Meta:
         verbose_name = "Workflow Notification"
         verbose_name_plural = "Workflow Notifications"
 
+    def clean(self):
+        from django.core.exceptions import ValidationError
+
+        if (
+            not self.notify_submitter
+            and not self.email_field
+            and not self.static_emails
+        ):
+            raise ValidationError(
+                "At least one recipient source must be set: "
+                "'Notify submitter', 'Email field', or 'Static emails'."
+            )
+
     def __str__(self) -> str:
-        recipient_desc = (
-            self.email_field
-            or (
+        parts = []
+        if self.notify_submitter:
+            parts.append("submitter")
+        if self.email_field:
+            parts.append(f"field:{self.email_field}")
+        if self.static_emails:
+            trimmed = (
                 self.static_emails[:40] + "…"
                 if len(self.static_emails) > 40
                 else self.static_emails
             )
-            or "(no recipients)"
-        )
+            parts.append(trimmed)
+        recipient_desc = ", ".join(parts) if parts else "(no recipients)"
         return f"{self.get_notification_type_display()} → {recipient_desc}"
 
 
diff --git a/django_forms_workflows/tasks.py b/django_forms_workflows/tasks.py
diff --git a/pyproject.toml b/pyproject.toml
