feat: standardised stage naming + fix approval page data rendering

matteius · claude · matteius · commit 5dbff2308176 · 2026-04-16T14:39:33.000-04:00
Adds ApprovalTask.display_label and format_stage_label() as the single
source of truth for stage labels. Format: "{swi.label}: Step {order}: {name}"
for sub-workflow tasks, "Step {order}: {name}" otherwise. Replaces scattered
one-off formatters and the hardcoded "Payment {index}" prefix in the
approval inbox serializer.

Fixes the "Prior Approval Step Responses" block on approve.html, which
was iterating section.fields as a flat list even though the builder
returns width-aware row groups. Rendering now delegates to the shared
_form_data_rows.html partial used by submission detail, restoring width
grouping, section headers, currency formatting ($X,XXX.XX), and
display_text rendering.

Also removes the workflow_name_label override in submission-detail stage
headers that was replacing per-stage names with a single workflow label.

Migration note: hosts whose SubWorkflowDefinition.label_template includes
stage-level detail (e.g. "Stage 2: Payment {index}") should update it to
just the instance portion ("Payment {index}"). The helper appends stage
info automatically.

Bumps version to 0.71.0.

Co-Authored-By: Claude Opus 4.7 (1M context) &lt;noreply@anthropic.com&gt;
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -7,6 +7,40 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.71.0] - 2026-04-16
+
+### Added
+- **`ApprovalTask.display_label` + `format_stage_label` helper** — single
+  source of truth for the standardised stage label rendered across every
+  surface. Format: `"{swi.label}: Step {stage.order}: {stage.name}"` for
+  sub-workflow tasks, `"Step {stage.order}: {stage.name}"` otherwise. Replaces
+  the hardcoded `"Payment {index}"` string in the approval inbox serializer
+  and scattered one-off formatters on the approval, submission detail, and
+  PDF surfaces.
+
+### Fixed
+- **Approval page "Prior Approval Step Responses" now honours width
+  grouping, section headers, and currency formatting** — the section was
+  iterating `section.fields` as a flat list despite the helper returning
+  width-aware row groups (pair/triple/full/section/display_text). Rendering
+  now delegates to the shared `_form_data_rows.html` partial already used
+  by submission detail, so the layout, currency symbols, and section
+  dividers match the rest of the app.
+- **Standardised stage naming across approval inbox, approval page,
+  submission detail, submission PDF, and bulk PDF.** Removed the
+  `workflow_name_label` override in submission-detail stage headers that
+  was hiding per-stage names, and dropped the hardcoded `"Payment"`
+  prefix in the inbox serializer (consumers should set
+  ``SubWorkflowDefinition.label_template`` appropriately, e.g.
+  `"Payment {index}"`).
+
+### Migration notes
+- If your deployment has a `SubWorkflowDefinition` whose `label_template`
+  includes stage-level detail (e.g. `"Stage 2: Payment {index}"`), update it
+  to just the instance portion (e.g. `"Payment {index}"`). The stage/step
+  information is now appended automatically by the label helper, so the
+  template should only describe the *instance*.
+
 ## [0.70.1] - 2026-04-16
 
 ### Fixed
diff --git a/django_forms_workflows/models.py b/django_forms_workflows/models.py
@@ -2399,6 +2399,45 @@ class Meta:
     def __str__(self):
         return f"{self.step_name} for {self.submission}"
 
+    @property
+    def display_label(self) -> str:
+        """Standardised human-readable label for this approval task.
+
+        Single source of truth shared by the approval inbox, approval page,
+        submission detail, and PDF exports so the same task reads identically
+        across every surface.
+
+        Format:
+          * Sub-workflow task →  ``"{swi.label}: Step {stage.order}: {stage.name}"``
+          * Otherwise        →  ``"Step {stage.order}: {stage.name}"``
+
+        Falls back gracefully when the stage or sub-workflow instance is missing.
+        """
+        stage = self.workflow_stage
+        swi = self.sub_workflow_instance
+        return format_stage_label(stage, swi=swi, fallback_name=self.step_name)
+
+
+def format_stage_label(stage, swi=None, fallback_name: str = "") -> str:
+    """Return the standardised display label for a workflow stage.
+
+    Shared helper used by views and templates that need to render a stage's
+    label the same way the approval inbox does, without needing an
+    ApprovalTask in hand (e.g. historical stages on submission detail or
+    PDF exports).
+    """
+    name = (getattr(stage, "name", None) or fallback_name or "").strip()
+    order = getattr(stage, "order", None)
+    step_part = f"Step {order}: {name}" if order and name else name
+    if swi is not None:
+        try:
+            swi_label = swi.label
+        except Exception:
+            swi_label = ""
+        if swi_label:
+            return f"{swi_label}: {step_part}" if step_part else swi_label
+    return step_part
+
 
 class AuditLog(models.Model):
     """
diff --git a/django_forms_workflows/templates/django_forms_workflows/approve.html b/django_forms_workflows/templates/django_forms_workflows/approve.html
@@ -209,7 +209,7 @@ <h5 class="mb-0"><i class="bi bi-paperclip"></i> Attachments</h5>
             <div class="card-header {% if section.status == 'approved' %}bg-success{% elif section.status == 'rejected' %}bg-danger{% else %}bg-secondary{% endif %} text-white">
                 <h5 class="mb-0">
                     <i class="bi {% if section.status == 'approved' %}bi-check-circle{% elif section.status == 'rejected' %}bi-x-circle{% else %}bi-hourglass{% endif %}"></i>
-                    {{ section.step_name }}
+                    {{ section.display_label|default:section.step_name }}
                     {% if section.status == 'approved' %}
                     <span class="badge bg-light text-success float-end">Approved</span>
                     {% elif section.status == 'rejected' %}
@@ -248,7 +248,7 @@ <h5 class="mb-0">
             <!-- Current Step Fields Section with Decision inline -->
             <div class="card mb-4 border-primary">
                 <div class="card-header bg-primary text-white">
-                    <h5 class="mb-0"><i class="bi bi-pencil-square"></i> {% if current_step_number %}Step {{ current_step_number }}: {% endif %}{{ task.step_name }}
+                    <h5 class="mb-0"><i class="bi bi-pencil-square"></i> {{ task.display_label }}
                         <span class="badge bg-light text-primary float-end">Your Action Required</span>
                     </h5>
                 </div>
@@ -398,7 +398,7 @@ <h5 class="mb-0"><i class="bi bi-pencil-square"></i> Prior Approval Step Respons
                     <div class="px-3 pt-3 pb-1 d-flex justify-content-between align-items-start flex-wrap gap-2">
                         <div>
                             <div class="d-flex align-items-center gap-2 mb-1">
-                                <h6 class="mb-0 fw-bold">{{ section.step_name }}</h6>
+                                <h6 class="mb-0 fw-bold">{{ section.display_label|default:section.step_name }}</h6>
                                 {% if section.status == "approved" %}
                                 <span class="badge bg-success">&#10003; Approved</span>
                                 {% elif section.status == "rejected" %}
@@ -421,53 +421,7 @@ <h6 class="mb-0 fw-bold">{{ section.step_name }}</h6>
                     {% if section.fields %}
                     <div class="px-3 pb-3">
                         <table class="table table-bordered table-sm mb-0">
-                            {% for field in section.fields %}
-                            <tr>
-                                <th style="width: 30%;">{{ field.label }}</th>
-                                <td>
-                                    {% if field.value.url %}
-                                        {% if field.value.content_type and 'image' in field.value.content_type %}
-                                            <div class="mb-2">
-                                                <img src="{{ field.value.url }}" alt="{{ field.value.filename }}" class="img-fluid" style="max-width: 400px; max-height: 400px;">
-                                            </div>
-                                        {% endif %}
-                                        <a href="{{ field.value.url }}" target="_blank" class="btn btn-sm btn-outline-primary">
-                                            <i class="bi bi-download"></i> {{ field.value.filename }}
-                                        </a>
-                                        <small class="text-muted ms-2">
-                                            {% if field.value.size %}({{ field.value.size|filesizeformat }}){% endif %}
-                                        </small>
-                                    {% elif field.value.path %}
-                                        <span class="text-muted">{{ field.value.filename }}</span>
-                                        <small class="text-muted ms-2">(File stored but URL unavailable)</small>
-                                    {% elif field.value|is_signature %}
-                                        <img src="{{ field.value }}" alt="Signature" class="img-fluid" style="max-width: 400px; max-height: 160px; border: 1px solid #dee2e6; border-radius: .375rem;">
-                                    {% elif field.value.0.filename %}
-                                        <ul class="list-unstyled mb-0">
-                                        {% for f in field.value %}
-                                            <li class="mb-1">
-                                                {% if f.url %}
-                                                    {% if f.content_type and 'image' in f.content_type %}
-                                                        <div class="mb-1">
-                                                            <img src="{{ f.url }}" alt="{{ f.filename }}" class="img-fluid" style="max-width: 200px; max-height: 200px;">
-                                                        </div>
-                                                    {% endif %}
-                                                    <a href="{{ f.url }}" target="_blank" class="btn btn-sm btn-outline-primary">
-                                                        <i class="bi bi-download"></i> {{ f.filename }}
-                                                    </a>
-                                                    <small class="text-muted ms-2">{% if f.size %}({{ f.size|filesizeformat }}){% endif %}</small>
-                                                {% else %}
-                                                    <span class="text-muted">{{ f.filename }}</span>
-                                                {% endif %}
-                                            </li>
-                                        {% endfor %}
-                                        </ul>
-                                    {% else %}
-                                        {{ field.value }}
-                                    {% endif %}
-                                </td>
-                            </tr>
-                            {% endfor %}
+                            {% include "django_forms_workflows/_form_data_rows.html" with form_data_ordered=section.fields %}
                         </table>
                     </div>
                     {% endif %}
diff --git a/django_forms_workflows/templates/django_forms_workflows/submission_bulk_pdf.html b/django_forms_workflows/templates/django_forms_workflows/submission_bulk_pdf.html
@@ -135,7 +135,7 @@
 
 {% if not item.hide_approval_history %}
 {% for section in item.approval_step_sections %}
-<div class="step-section-header">{{ section.step_name }}</div>
+<div class="step-section-header">{{ section.display_label|default:section.step_name }}</div>
 <p class="step-meta">
     {% if section.completed_by %}Completed by {{ section.completed_by }}{% if section.completed_at %} &middot; {{ section.completed_at|date:"N j, Y \a\t g:i a" }}{% endif %}{% endif %}
     {% if section.comments %}&nbsp;&nbsp;Comment: {{ section.comments }}{% endif %}
diff --git a/django_forms_workflows/templates/django_forms_workflows/submission_detail.html b/django_forms_workflows/templates/django_forms_workflows/submission_detail.html
@@ -125,7 +125,7 @@ <h5 class="mb-0"><i class="bi bi-pencil-square"></i> Approval Step Responses</h5
                     <div class="px-3 pt-3 pb-1 d-flex justify-content-between align-items-start flex-wrap gap-2">
                         <div>
                             <div class="d-flex align-items-center gap-2 mb-1">
-                                <h6 class="mb-0 fw-bold">{{ section.step_name }}</h6>
+                                <h6 class="mb-0 fw-bold">{{ section.display_label|default:section.step_name }}</h6>
                                 {% if section.status == "approved" %}
                                 <span class="badge bg-success">&#10003; Approved</span>
                                 {% elif section.status == "rejected" %}
@@ -208,7 +208,7 @@ <h5 class="mb-3"><i class="bi bi-diagram-3"></i> Approval History</h5>
                 {% elif stage.approved_count > 0 %}bg-primary text-white
                 {% else %}bg-light text-muted{% endif %}">
                 <span>
-                    <strong>{% if workflow_name_label %}{{ workflow_name_label }}{% else %}Stage {{ stage.number }}{% if not stage.has_multiple_stages %}: {{ stage.name }}{% endif %}{% endif %}</strong>
+                    <strong>{% if stage.has_multiple_stages %}Stage {{ stage.number }}{% else %}{{ stage.display_label }}{% endif %}</strong>
                 </span>
                 <span class="badge bg-white
                     {% if stage.rejected_count > 0 %}text-danger
@@ -234,7 +234,7 @@ <h5 class="mb-3"><i class="bi bi-diagram-3"></i> Approval History</h5>
                         <tbody>
                             {% for task in stage.tasks %}
                             <tr>
-                                <td><strong>{{ task.step_display_name }}</strong></td>
+                                <td><strong>{{ task.display_label }}</strong></td>
                                 <td>
                                     {% if task.assigned_to %}
                                         {{ task.assigned_to.get_full_name|default:task.assigned_to.username }}
@@ -303,7 +303,7 @@ <h5 class="mb-3"><i class="bi bi-diagram-3"></i> Approval History</h5>
                             {% for stage in section.stage_groups %}
                             {% for task in stage.tasks %}
                             <tr>
-                                <td><strong>{{ stage.name }}</strong></td>
+                                <td><strong>{{ task.display_label }}</strong></td>
                                 <td>
                                     {% if task.assigned_to %}
                                         {{ task.assigned_to.get_full_name|default:task.assigned_to.username }}
@@ -355,7 +355,7 @@ <h5 class="mb-0">Approval History</h5>
                         <tbody>
                             {% for task in approval_tasks %}
                             <tr>
-                                <td>{{ task.step_name }}</td>
+                                <td>{{ task.display_label }}</td>
                                 <td>
                                     {% if task.assigned_to %}
                                         {{ task.assigned_to.get_full_name|default:task.assigned_to.username }}
diff --git a/django_forms_workflows/templates/django_forms_workflows/submission_pdf.html b/django_forms_workflows/templates/django_forms_workflows/submission_pdf.html
@@ -268,7 +268,7 @@ <h3 style="margin-top: 20px;">Attachments</h3>
 {% if not hide_approval_history %}
 {% for section in approval_step_sections %}
 <div class="step-section-header">
-    <span class="step-name-cell">{{ section.step_name }}</span>
+    <span class="step-name-cell">{{ section.display_label|default:section.step_name }}</span>
     <span class="step-badge-cell">
         {% if section.status == "approved" %}
         <span class="step-badge step-badge-approved">&#10003; Approved</span>
diff --git a/django_forms_workflows/views.py b/django_forms_workflows/views.py
@@ -1106,6 +1106,7 @@ def submission_detail(request, submission_id):
                 target[stage_key] = {
                     "number": task.stage_number or 0,
                     "name": stage_name,
+                    "display_label": task.display_label,
                     "approval_logic": (
                         task.workflow_stage.approval_logic
                         if task.workflow_stage
@@ -1196,6 +1197,7 @@ def submission_detail(request, submission_id):
                     stage_map[stage_key] = {
                         "number": task.stage_number or 0,
                         "name": stage_name,
+                        "display_label": task.display_label,
                         "approval_logic": approval_logic,
                         "tasks": [],
                         "approved_count": 0,
@@ -3456,15 +3458,16 @@ def _build_approval_step_sections(submission):
                 task.completed_by.get_full_name() or task.completed_by.username
             )
 
-        # Section header: use the stored step_name directly; it now bakes in
-        # the stage's approve_label when tasks are created (workflow_engine.py).
+        # Section header: use the task's centralised display_label so the
+        # section header matches the inbox / approve / PDF rendering exactly.
         stage_order = task.stage_number or task.step_number or 1
         step_name = task.step_name or f"Step {stage_order}"
 
         sections.append(
             {
                 "step_number": stage_order,
                 "step_name": step_name,
+                "display_label": task.display_label,
                 "status": task.status,
                 "group_name": (
                     task.assigned_group.name if task.assigned_group else None
@@ -4186,12 +4189,10 @@ def approval_inbox_ajax(request):
         approve_url = reverse("forms_workflows:approve_submission", args=[task.id])
         det_url = reverse("forms_workflows:submission_detail", args=[sub.id])
 
-        # For sub-workflow tasks, prefix the stage name with the instance index
-        # so "Payment Request" becomes "Payment 1: Payment Request".
-        stage_name = task.workflow_stage.name if task.workflow_stage else ""
-        swi = task.sub_workflow_instance
-        if swi and stage_name:
-            stage_name = f"Payment {swi.index}: {stage_name}"
+        # Standardised label used across inbox, approve page, submission
+        # detail, and PDFs — driven by ApprovalTask.display_label so any
+        # format change happens in one place.
+        stage_name = task.display_label
 
         row = {
             "DT_RowId": f"row_{task.id}",
diff --git a/pyproject.toml b/pyproject.toml
@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "django-forms-workflows"
-version = "0.70.1"
+version = "0.71.0"
 description = "Enterprise-grade, database-driven form builder with approval workflows and external data integration"
 license = "LGPL-3.0-only"
 readme = "README.md"
