feat: release 0.54.0 — success pages, answer piping, notification subject piping, 29 new tests, docs

Author: matteius

CHANGELOG.md

@@ -7,6 +7,32 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.54.0] - 2026-04-01
+
+### Added
+- **Success Pages** — Three new fields on `FormDefinition` control post-submission routing, evaluated in priority order:
+  - `success_redirect_rules` (JSONField) — array of conditional redirect rules; first match wins. Each rule combines a `url` with any condition the existing evaluate-conditions engine understands (simple field equality, compound AND/OR, etc.).
+  - `success_redirect_url` (CharField) — static redirect URL, applied when no rule matches.
+  - `success_message` (TextField) — custom HTML rendered at `/submissions/<id>/success/` when no redirect is configured.
+  - New `submission_success` URL (`forms_workflows:submission_success`) and view; template `submission_success.html` with "My Submissions" / "Back to Forms" navigation.
+- **Answer piping** — `{field_name}` token substitution available in three places:
+  - *Success messages & redirect URLs* — `_pipe_answer_tokens()` helper resolves tokens server-side from `form_data`; list-valued fields are comma-joined; unknown tokens become empty strings.
+  - *Notification subjects* — `subject_template` on `NotificationRule` now resolves `{field_name}` tokens alongside `{form_name}` and `{submission_id}` via a `defaultdict(str)` (fail-open: unknown tokens → empty string).
+  - *Live form labels* — new JS block in `form_submit.html` scans `<label>`, `<small>`, and `.form-text` elements for tokens, attaches `input`/`change` listeners, and replaces them in real-time as the user types.
+- **`form_data` in notification email context** — the full `form_data` dict is now passed to every notification template so HTML templates can reference `{{ form_data.field_name }}` directly.
+- **Form builder: Success Page settings panel** — redirect URL input, conditional rules JSON editor, success message textarea with piping syntax hints, and a CAPTCHA toggle; all values round-trip through `form_builder_load` / `form_builder_save`.
+- **Migration `0081`** (`0081_add_success_page_fields`) — adds `success_message`, `success_redirect_url`, and `success_redirect_rules` to `FormDefinition`.
+
+### Documentation
+- `docs/POST_SUBMISSION_ACTIONS.md` — new **Success Pages** and **Answer Piping** sections.
+- `docs/NOTIFICATIONS.md` — new **Answer Piping in Subjects** section; `form_data` template context documented.
+- `docs/FORM_BUILDER_USER_GUIDE.md` — Submission Controls panel, Success Page settings panel, palette search, and four new field types documented.
+- `docs/CLIENT_SIDE_ENHANCEMENTS.md` — new **Real-Time Answer Piping** section (§ 6).
+
+### Tests
+- New tests in `tests/test_views.py`: `TestPipeAnswerTokens` (9 cases), `TestSubmissionSuccessView` (5 cases), `TestSuccessRouting` (10 cases).
+- New tests in `tests/test_notifications.py`: 5 cases covering subject piping, unknown-field fail-open, built-in placeholders, list-value comma-join, and `form_data` in template context.
+
 ## [0.53.0] - 2026-04-01
 
 ### Added

django_forms_workflows/form_builder_views.py

@@ -311,6 +311,9 @@ def form_builder_load(request, form_id):
         "requires_login": form_definition.requires_login,
         "allow_save_draft": form_definition.allow_save_draft,
         "allow_withdrawal": form_definition.allow_withdrawal,
+        "success_message": form_definition.success_message or "",
+        "success_redirect_url": form_definition.success_redirect_url or "",
+        "success_redirect_rules": form_definition.success_redirect_rules,
         "close_date": form_definition.close_date.isoformat()
         if form_definition.close_date
         else None,
@@ -349,6 +352,9 @@ def form_builder_save(request):
         requires_login = data.get("requires_login", True)
         allow_save_draft = data.get("allow_save_draft", True)
         allow_withdrawal = data.get("allow_withdrawal", True)
+        success_message = data.get("success_message", "").strip()
+        success_redirect_url = data.get("success_redirect_url", "").strip()
+        success_redirect_rules = data.get("success_redirect_rules") or None
         close_date = data.get("close_date") or None
         max_submissions = data.get("max_submissions") or None
         one_per_user = data.get("one_per_user", False)
@@ -382,6 +388,9 @@ def form_builder_save(request):
                 form_definition.requires_login = requires_login
                 form_definition.allow_save_draft = allow_save_draft
                 form_definition.allow_withdrawal = allow_withdrawal
+                form_definition.success_message = success_message
+                form_definition.success_redirect_url = success_redirect_url
+                form_definition.success_redirect_rules = success_redirect_rules
                 form_definition.close_date = close_date
                 form_definition.max_submissions = max_submissions
                 form_definition.one_per_user = one_per_user
@@ -402,6 +411,9 @@ def form_builder_save(request):
                     requires_login=requires_login,
                     allow_save_draft=allow_save_draft,
                     allow_withdrawal=allow_withdrawal,
+                    success_message=success_message,
+                    success_redirect_url=success_redirect_url,
+                    success_redirect_rules=success_redirect_rules,
                     close_date=close_date,
                     max_submissions=max_submissions,
                     one_per_user=one_per_user,

django_forms_workflows/migrations/0081_add_success_page_fields.py

@@ -0,0 +1,41 @@
+# Generated by Django 5.2.7 on 2026-04-01 10:30
+
+from django.db import migrations, models
+
+
+class Migration(migrations.Migration):
+
+    dependencies = [
+        (
+            "django_forms_workflows",
+            "0080_add_rating_matrix_address_slider_fields_and_form_controls",
+        ),
+    ]
+
+    operations = [
+        migrations.AddField(
+            model_name="formdefinition",
+            name="success_message",
+            field=models.TextField(
+                blank=True,
+                help_text="Custom HTML shown after submission. Supports answer piping with {field_name} tokens that are replaced with the submitted values. Leave blank for the default confirmation message.",
+            ),
+        ),
+        migrations.AddField(
+            model_name="formdefinition",
+            name="success_redirect_rules",
+            field=models.JSONField(
+                blank=True,
+                help_text='Conditional redirects based on form data. Format: [{"field": "field_name", "operator": "equals", "value": "...", "url": "https://..."}]. First matching rule wins; falls back to success_redirect_url or the default page.',
+                null=True,
+            ),
+        ),
+        migrations.AddField(
+            model_name="formdefinition",
+            name="success_redirect_url",
+            field=models.URLField(
+                blank=True,
+                help_text="Redirect to this URL after submission instead of showing a success page.",
+            ),
+        ),
+    ]

django_forms_workflows/models.py

@@ -252,6 +252,29 @@ class FormDefinition(models.Model):
         help_text="Auto-save interval in seconds",
     )
 
+    # Success Page
+    success_message = models.TextField(
+        blank=True,
+        help_text=(
+            "Custom HTML shown after submission. Supports answer piping with "
+            "{field_name} tokens that are replaced with the submitted values. "
+            "Leave blank for the default confirmation message."
+        ),
+    )
+    success_redirect_url = models.URLField(
+        blank=True,
+        help_text="Redirect to this URL after submission instead of showing a success page.",
+    )
+    success_redirect_rules = models.JSONField(
+        blank=True,
+        null=True,
+        help_text=(
+            "Conditional redirects based on form data. Format: "
+            '[{"field": "field_name", "operator": "equals", "value": "...", "url": "https://..."}]. '
+            "First matching rule wins; falls back to success_redirect_url or the default page."
+        ),
+    )
+
     # PDF Generation
     PDF_GENERATION_CHOICES = [
         ("none", "Disabled"),

django_forms_workflows/static/django_forms_workflows/js/form-builder.js

@@ -1955,6 +1955,11 @@ class FormBuilder {
             document.getElementById('formAllowDraft').checked = data.allow_save_draft;
             document.getElementById('formAllowWithdrawal').checked = data.allow_withdrawal;
 
+            // Load success page settings
+            document.getElementById('formSuccessMessage').value = data.success_message || '';
+            document.getElementById('formSuccessRedirectUrl').value = data.success_redirect_url || '';
+            document.getElementById('formSuccessRedirectRules').value = data.success_redirect_rules ? JSON.stringify(data.success_redirect_rules) : '';
+
             // Load submission controls
             if (data.close_date) document.getElementById('formCloseDate').value = data.close_date.slice(0, 16);
             if (data.max_submissions) document.getElementById('formMaxSubmissions').value = data.max_submissions;
@@ -2018,6 +2023,9 @@ class FormBuilder {
             requires_login: document.getElementById('formRequiresLogin').checked,
             allow_save_draft: document.getElementById('formAllowDraft').checked,
             allow_withdrawal: document.getElementById('formAllowWithdrawal').checked,
+            success_message: document.getElementById('formSuccessMessage').value.trim(),
+            success_redirect_url: document.getElementById('formSuccessRedirectUrl').value.trim(),
+            success_redirect_rules: (() => { try { const v = document.getElementById('formSuccessRedirectRules').value.trim(); return v ? JSON.parse(v) : null; } catch(e) { return null; } })(),
             close_date: document.getElementById('formCloseDate').value || null,
             max_submissions: parseInt(document.getElementById('formMaxSubmissions').value) || null,
             one_per_user: document.getElementById('formOnePerUser').checked,

django_forms_workflows/tasks.py

@@ -1200,17 +1200,28 @@ def send_notification_rules(
             )
             continue
 
-        subject = (
-            rule.subject_template.format(
-                form_name=form_name, submission_id=submission.id
-            )
-            if rule.subject_template
-            else default_subject_tpl.format(
+        # Build subject with answer piping — {field_name} tokens are
+        # resolved from form_data alongside the built-in {form_name} and
+        # {submission_id} placeholders.
+        _pipe_vars = {
+            "form_name": form_name,
+            "submission_id": submission.id,
+            **{
+                k: (", ".join(v) if isinstance(v, list) else str(v))
+                for k, v in form_data.items()
+            },
+        }
+        subject_tpl = rule.subject_template or default_subject_tpl
+        try:
+            subject = subject_tpl.format_map(defaultdict(str, _pipe_vars))
+        except Exception:
+            subject = subject_tpl.format(
                 form_name=form_name, submission_id=submission.id
             )
-        )
+
         context = {
             "submission": submission,
+            "form_data": form_data,
             "submission_url": submission_url,
             "approval_url": approval_url,
             "hide_approval_history": hide_approval_history,

django_forms_workflows/templates/admin/django_forms_workflows/form_builder.html

@@ -711,6 +711,27 @@ <h5 class="mb-0"><i class="bi bi-gear"></i> Form Settings</h5>
                         </div>
                     </div>
 
+                    <!-- Success Page -->
+                    <div class="col-12 mt-3">
+                        <h6 class="text-muted border-bottom pb-2">
+                            <i class="bi bi-check-circle"></i> Success Page
+                        </h6>
+                    </div>
+                    <div class="col-md-6">
+                        <label class="form-label small">Redirect URL <span class="text-muted">(optional)</span></label>
+                        <input type="url" class="form-control form-control-sm" id="formSuccessRedirectUrl" placeholder="https://example.com/thank-you">
+                        <small class="text-muted">Redirect here after submission. Supports <code>{field_name}</code> tokens.</small>
+                    </div>
+                    <div class="col-md-6">
+                        <label class="form-label small">Conditional Redirects <span class="text-muted">(JSON, optional)</span></label>
+                        <input type="text" class="form-control form-control-sm font-monospace" id="formSuccessRedirectRules" placeholder='[{"field":"...", "operator":"equals", "value":"...", "url":"..."}]'>
+                    </div>
+                    <div class="col-12">
+                        <label class="form-label small">Custom Success Message <span class="text-muted">(HTML, optional)</span></label>
+                        <textarea class="form-control form-control-sm" id="formSuccessMessage" rows="3" placeholder="Thank you, {first_name}! Your {form_type} request has been submitted."></textarea>
+                        <small class="text-muted">Shown after submission. Use <code>{field_name}</code> for answer piping. Leave blank for default.</small>
+                    </div>
+
                     <!-- Submission Controls -->
                     <div class="col-12 mt-3">
                         <h6 class="text-muted border-bottom pb-2">

django_forms_workflows/templates/django_forms_workflows/form_submit.html

@@ -203,6 +203,60 @@ <h1>{{ form_def.name }}</h1>
         document.querySelectorAll('form').forEach(wireCalculatedFields);
     })();
 
+    // ── Answer piping: replace {field_name} tokens in labels & help text ─
+    (function () {
+        var form = document.querySelector('[data-form-enhancements="true"]');
+        if (!form) return;
+
+        // Find all labels and help-text spans that contain {tokens}
+        var TOKEN_RE = /\{(\w+)\}/g;
+        var pipeTargets = [];
+
+        form.querySelectorAll('label, .form-text, .help-block, small').forEach(function (el) {
+            var tpl = el.textContent;
+            if (TOKEN_RE.test(tpl)) {
+                pipeTargets.push({ el: el, template: tpl });
+            }
+            TOKEN_RE.lastIndex = 0; // reset regex state
+        });
+
+        if (!pipeTargets.length) return;
+
+        // Collect all referenced field names
+        var sourceNames = new Set();
+        pipeTargets.forEach(function (t) {
+            var m;
+            TOKEN_RE.lastIndex = 0;
+            while ((m = TOKEN_RE.exec(t.template)) !== null) {
+                sourceNames.add(m[1]);
+            }
+        });
+
+        function updatePipes() {
+            pipeTargets.forEach(function (t) {
+                t.el.textContent = t.template.replace(TOKEN_RE, function (_, name) {
+                    var el = form.querySelector('[name="' + name + '"]');
+                    if (!el) return '{' + name + '}';
+                    if (el.type === 'checkbox') return el.checked ? (el.value || 'Yes') : '';
+                    if (el.tagName === 'SELECT') {
+                        var opt = el.options[el.selectedIndex];
+                        return opt ? opt.text : '';
+                    }
+                    return el.value || '';
+                });
+            });
+        }
+
+        sourceNames.forEach(function (name) {
+            var el = form.querySelector('[name="' + name + '"]');
+            if (el) {
+                el.addEventListener('input', updatePipes);
+                el.addEventListener('change', updatePipes);
+            }
+        });
+        updatePipes();
+    })();
+
     // ── Rating stars widget ──────────────────────────────────────────────
     (function () {
         document.querySelectorAll('.rating-stars-input').forEach(function (select) {

django_forms_workflows/templates/django_forms_workflows/submission_success.html

@@ -0,0 +1,30 @@
+{% extends "django_forms_workflows/base.html" %}
+
+{% block title %}Submission Received — {{ form_def.name }}{% endblock %}
+
+{% block content %}
+<div class="container py-5">
+    <div class="row justify-content-center">
+        <div class="col-md-8 col-lg-6">
+            <div class="card shadow-sm p-4">
+                <div class="text-center mb-4">
+                    <i class="bi bi-check-circle-fill text-success" style="font-size: 3.5rem;"></i>
+                </div>
+                <div class="success-message">
+                    {{ success_message|safe }}
+                </div>
+                <div class="d-grid gap-2 mt-4">
+                    {% if request.user.is_authenticated %}
+                    <a href="{% url 'forms_workflows:my_submissions' %}" class="btn btn-primary">
+                        <i class="bi bi-list-check"></i> My Submissions
+                    </a>
+                    {% endif %}
+                    <a href="{% url 'forms_workflows:form_list' %}" class="btn btn-outline-secondary">
+                        <i class="bi bi-arrow-left"></i> Back to Forms
+                    </a>
+                </div>
+            </div>
+        </div>
+    </div>
+</div>
+{% endblock %}

django_forms_workflows/urls.py

@@ -84,6 +84,12 @@
         views.reassign_task,
         name="reassign_task",
     ),
+    # Custom success page (per-submission, supports answer piping)
+    path(
+        "submissions/<int:submission_id>/success/",
+        views.submission_success,
+        name="submission_success",
+    ),
     # Public form submission confirmation (no login required)
     path(
         "submitted/",