domma-cms 1.6.59 → 1.7.0

package/docs/superpowers/specs/plans/2026-03-12-form-followup-actions.md

@@ -0,0 +1,624 @@
+# Form Follow-Up: Success States & Action Triggers - Implementation Plan
+
+> **For agentic workers:** REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or
+> superpowers:executing-plans to implement this plan. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Wire CMS Actions to auto-execute on form submission, add configurable success redirect, and document the full
+flow with a tutorial and example page.
+
+**Architecture:** Two new optional fields (`settings.actionSlug`, `settings.successRedirect`) in each form's JSON. The
+server-side submission pipeline executes the named Action after storing the entry (non-fatal, try/catch). The client
+reads the `redirect` field from the response and either redirects or shows the inline success message.
+
+**Tech Stack:** Fastify (ESM), Node.js file-based forms, Domma public site JS (`H.post`, `F.render`), static HTML
+templates for admin docs/tutorials.
+
+**Spec:** `docs/superpowers/specs/2026-03-12-form-followup-actions-design.md`
+
+---
+
+## Chunk 1: Server - action trigger + redirect response
+
+### Task 1: Add executeAction import and trigger to form submission
+
+**Files:**
+
+- Modify: `server/routes/api/forms.js`
+
+The submission handler lives at `POST /forms/submit/:slug` (line 312). The webhook block ends around line 428 with a
+`fastify.log.warn`. Add the action execution block immediately after it, then update the return value to include
+`redirect`.
+
+- [ ] **Step 1: Add import for executeAction**
+
+At the top of `server/routes/api/forms.js`, add `executeAction` to the imports from collections. It actually lives in
+`server/services/actions.js`. Add a new import line after the existing imports:
+
+```js
+import {executeAction} from '../../services/actions.js';
+```
+
+- [ ] **Step 2: Add action execution block after the webhook block**
+
+Locate this line in the submission handler (around line 428):
+
+```js
+        // Webhook action
+        const webhookAction = form.actions?.webhook;
+```
+
+After the entire webhook try/catch block (which ends around line 429), insert:
+
+```js
+        // CMS Action trigger
+        const actionSlug = form.settings?.actionSlug;
+        if (actionSlug && entry) {
+            try {
+                await executeAction(actionSlug, entry.id, { user: null });
+            } catch (err) {
+                fastify.log.warn(`[forms] Action "${actionSlug}" failed for form "${slug}": ${err.message}`);
+            }
+        }
+```
+
+Note: `entry` is the result of `createEntry(...)` - currently it's not stored in a variable. You need to capture it.
+Change this existing line:
+
+```js
+// BEFORE:
+await createEntry(targetSlug, data, { source: `form:${slug}` });
+
+// AFTER:
+entry = await createEntry(targetSlug, data, { source: `form:${slug}` });
+```
+
+And declare `let entry = null;` before the collection try/catch block.
+
+- [ ] **Step 3: Update the return value to include redirect**
+
+Locate the final return at the bottom of the submit handler:
+
+```js
+        return { ok: true, message: settings.successMessage || 'Thank you for your submission.' };
+```
+
+Replace with:
+
+```js
+        return {
+            ok:       true,
+            message:  settings.successMessage  || 'Thank you for your submission.',
+            redirect: settings.successRedirect || null
+        };
+```
+
+Also update the honeypot early-return to match:
+
+```js
+// BEFORE:
+        return { ok: true, message: settings.successMessage };
+
+// AFTER:
+        return { ok: true, message: settings.successMessage, redirect: settings.successRedirect || null };
+```
+
+- [ ] **Step 4: Verify syntax**
+
+```bash
+node --check server/routes/api/forms.js
+```
+
+Expected: no output (no errors).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add server/routes/api/forms.js
+git commit -m "feat: execute CMS action and return redirect on form submission"
+```
+
+---
+
+## Chunk 2: Admin form editor - new settings fields
+
+### Task 2: Add HTML fields to form-editor template
+
+**Files:**
+
+- Modify: `admin/js/templates/form-editor.html`
+
+The Settings tab panel starts around line 102. The `setting-success-message` textarea is at line 113-115. Add two new
+fields directly after it.
+
+- [ ] **Step 1: Add Success Redirect URL field after success message**
+
+Locate:
+
+```html
+            <textarea id="setting-success-message" class="form-input" rows="3"
+                      placeholder="Thank you for your submission."></textarea>
+          </div>
+```
+
+Insert immediately after the closing `</div>`:
+
+```html
+          <div class="mb-3">
+            <label class="form-label">Success Redirect URL</label>
+            <input id="setting-success-redirect" type="text" class="form-input"
+                   placeholder="/thank-you">
+            <p class="form-hint text-muted" style="margin-top:.3rem;font-size:.8rem;">
+              If set, redirects the visitor to this URL on success. Takes priority over the success message.
+            </p>
+          </div>
+```
+
+- [ ] **Step 2: Add CMS Action card to the Actions tab**
+
+The Actions tab (Tab 4) begins around line 141. It has an Email card, Webhook card, and Spam Protection card. Add a
+new "CMS Action" card as the third column card. Locate the closing `</div>` of the `<div class="row">` wrapper (around
+line 190) and add a new card inside the row before it closes:
+
+```html
+        <div class="col-6">
+          <div class="card mb-4">
+            <div class="card-header"><h2>CMS Action</h2></div>
+            <div class="card-body">
+              <div class="mb-3">
+                <label class="form-label">Action on Submit</label>
+                <select id="action-cms-slug" class="form-input">
+                  <option value="">- None -</option>
+                </select>
+                <p class="form-hint text-muted" style="margin-top:.3rem;font-size:.8rem;">
+                  Run a CMS Action after the entry is stored. Requires Pro (MongoDB).
+                  Failures are non-fatal - the submission is always saved first.
+                </p>
+              </div>
+            </div>
+          </div>
+        </div>
+```
+
+- [ ] **Step 3: Verify the template renders (visual check only - no syntax errors)**
+
+Check that the HTML is valid (no unclosed tags) by reading the modified section.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add admin/js/templates/form-editor.html
+git commit -m "feat: add success redirect and CMS action fields to form editor template"
+```
+
+---
+
+### Task 3: Wire new fields in form-editor JS
+
+**Files:**
+
+- Modify: `admin/js/views/form-editor.js`
+
+Three changes: collect, populate, and load actions into the select.
+
+- [ ] **Step 1: Add fields to collectFormData()**
+
+Locate `collectFormData()` (around line 1172). Inside the `settings` object (line 1180), add the two new fields after
+`rateLimitPerMinute`:
+
+```js
+// Add after:
+            rateLimitPerMinute: parseInt($container.find('#setting-rate-limit').val(), 10) || 3
+
+// Insert:
+            ,
+            successRedirect: $container.find('#setting-success-redirect').val().trim() || null,
+            actionSlug:      $container.find('#action-cms-slug').val() || null
+```
+
+- [ ] **Step 2: Populate fields when loading an existing form**
+
+Locate the populate section (around line 1320) where `const s = form.settings || {};` is. Add population after the
+existing `rateLimitPerMinute` line:
+
+```js
+// Add after:
+            $container.find('#setting-rate-limit').val(s.rateLimitPerMinute || 3);
+
+// Insert:
+            $container.find('#setting-success-redirect').val(s.successRedirect || '');
+            // actionSlug select populated after actions are loaded (see loadActions below)
+```
+
+- [ ] **Step 3: Add loadActions() call in onMount**
+
+Find the `onMount` function (it calls `E.tabs(...)` and populates form data). After the tabs init and form population,
+add a call to load available actions. Find where `$container.find('#action-email-enabled')` is populated (around line
+1330) and add after the webhook section:
+
+```js
+            // Load CMS Actions into select
+            const savedActionSlug = form?.settings?.actionSlug || '';
+            try {
+                const actions = await apiRequest('/actions').catch(() => []);
+                const sel = $container.find('#action-cms-slug').get(0);
+                (Array.isArray(actions) ? actions : []).forEach(a => {
+                    const opt = document.createElement('option');
+                    opt.value = a.slug;
+                    opt.textContent = a.title || a.slug;
+                    if (a.slug === savedActionSlug) opt.selected = true;
+                    sel.appendChild(opt);
+                });
+                if (!actions.length) {
+                    const opt = document.createElement('option');
+                    opt.value = '';
+                    opt.textContent = 'No actions available';
+                    opt.disabled = true;
+                    sel.appendChild(opt);
+                }
+            } catch {
+                // Actions endpoint unavailable (Pro feature not configured) - leave select empty
+            }
+```
+
+- [ ] **Step 4: Verify syntax**
+
+```bash
+node --check admin/js/views/form-editor.js
+```
+
+Expected: no output.
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add admin/js/views/form-editor.js
+git commit -m "feat: collect, populate, and load CMS action + success redirect in form editor"
+```
+
+---
+
+## Chunk 3: Public site - handle redirect and inline success
+
+### Task 4: Update hydrateFormEmbeds to handle redirect
+
+**Files:**
+
+- Modify: `public/js/site.js`
+
+The `onSubmit` handler is at line 497-506. Currently it awaits `H.post` without capturing the return value, then
+immediately clears the form and calls `showResult`. Update it to check for `redirect` in the response.
+
+- [ ] **Step 1: Capture response and handle redirect**
+
+Locate this block (around line 497):
+
+```js
+        const onSubmit = async (formData) => {
+            try {
+                await H.post(`/api/forms/submit/${form.slug}`, formData);
+                while (el.firstChild) el.removeChild(el.firstChild);
+                showResult(el, s.successMessage || 'Thank you for your submission.', false);
+            } catch (err) {
+                showResult(el, err.message || 'Submission failed. Please try again.', true);
+                throw err; // re-throw so Domma knows the submit failed
+            }
+        };
+```
+
+Replace with:
+
+```js
+        const onSubmit = async (formData) => {
+            try {
+                const result = await H.post(`/api/forms/submit/${form.slug}`, formData);
+                if (result?.redirect) {
+                    window.location.href = result.redirect;
+                    return;
+                }
+                while (el.firstChild) el.removeChild(el.firstChild);
+                showResult(el, result?.message || s.successMessage || 'Thank you for your submission.', false);
+            } catch (err) {
+                showResult(el, err.message || 'Submission failed. Please try again.', true);
+                throw err; // re-throw so Domma knows the submit failed
+            }
+        };
+```
+
+- [ ] **Step 2: Verify syntax**
+
+```bash
+node --check public/js/site.js
+```
+
+Expected: no output.
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add public/js/site.js
+git commit -m "feat: handle redirect and success message response in form embed hydration"
+```
+
+---
+
+## Chunk 4: Example content + tutorial + documentation
+
+### Task 5: Create thank-you page and update enquiries form
+
+**Files:**
+
+- Create: `content/pages/thank-you.md`
+- Modify: `content/forms/enquiries.json`
+
+- [ ] **Step 1: Create thank-you page**
+
+Create `content/pages/thank-you.md`:
+
+```markdown
+---
+title: Thank You
+slug: thank-you
+description: Your message has been received
+layout: default
+status: published
+sortOrder: 99
+showInNav: false
+sidebar: false
+visibility: public
+createdAt: '2026-03-12T00:00:00.000Z'
+updatedAt: '2026-03-12T00:00:00.000Z'
+---
+
+[hero variant="dark" size="md" fullwidth="true"]
+
+# Thank You
+
+[scribe]Your message has been received. We'll be in touch shortly.[/scribe]
+
+[/hero]
+
+[spacer /]
+
+[card]
+
+Thanks for getting in touch. We aim to respond within one business day.
+
+[Back to Home](/)
+
+[/card]
+```
+
+- [ ] **Step 2: Update enquiries form to use successRedirect**
+
+Read `content/forms/enquiries.json` first, then update the `settings` block to add:
+
+```json
+"successRedirect": "/thank-you",
+"actionSlug": null
+```
+
+The `actionSlug` is `null` since this is a free-tier example (no MongoDB required). The redirect is the primary success
+UX for this form.
+
+- [ ] **Step 3: Update contact.md to note the form behaviour**
+
+The contact page (`content/pages/contact.md`) already uses `<div data-form="enquiries"></div>`. No markup changes
+needed - the redirect is configured in the form JSON. Optionally add a brief note in the page body:
+
+```markdown
+[spacer /]
+
+> **Note for developers:** This form is configured with a success redirect to `/thank-you`. To add a CMS Action trigger (Pro), set `actionSlug` in `content/forms/enquiries.json`.
+```
+
+This is optional - remove if it feels too developer-facing for a public contact page.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add content/pages/thank-you.md content/forms/enquiries.json content/pages/contact.md
+git commit -m "feat: add thank-you page and configure enquiries form with success redirect"
+```
+
+---
+
+### Task 6: Add tutorial card to tutorials.html
+
+**Files:**
+
+- Modify: `admin/js/templates/tutorials.html`
+
+The file currently has one card: "Writing a Plugin". It ends around line 231-233. Add a new collapsible card after it.
+
+- [ ] **Step 1: Add the tutorial card**
+
+Locate the closing tags near the end of `tutorials.html`:
+
+```html
+  </div>
+</div>
+```
+
+Insert the new card before these closing tags:
+
+```html
+  <!-- Tutorial: Form Follow-Up -->
+  <div class="card card-collapsible mb-4">
+    <div class="card-header">
+      <h2>Form Follow-Up: Notifications &amp; Actions</h2>
+    </div>
+    <div class="card-body">
+
+      <p>Every form in Domma CMS can trigger up to four things after a submission is stored:</p>
+      <ol>
+        <li>Send an <strong>email notification</strong> to one or more recipients</li>
+        <li>POST to a <strong>webhook URL</strong></li>
+        <li>Execute a <strong>CMS Action</strong> (Pro)</li>
+        <li>Redirect the visitor to a <strong>success page</strong> (or show an inline message)</li>
+      </ol>
+      <p>These are configured per-form in the admin. Open any form in <a href="#/forms">Forms</a> and go to the
+        <strong>Settings</strong> and <strong>Actions</strong> tabs.</p>
+
+      <hr>
+
+      <h3>1. Email notification</h3>
+      <p>Go to the <strong>Actions</strong> tab of your form and enable <em>Send email on submit</em>. Enter one or
+        more comma-separated recipient addresses. This uses the SMTP settings configured in
+        <a href="#/settings">Site Settings → Email / SMTP</a>.</p>
+
+      <pre class="code-block"><code>Recipients:       admin@example.com, team@example.com
+Subject Prefix:   [Contact Form]</code></pre>
+
+      <h3>2. Webhook</h3>
+      <p>Enable <em>POST to webhook on submit</em> and enter a URL. Domma will POST the following JSON body:</p>
+      <pre class="code-block"><code>{
+  "form": "enquiries",
+  "data": {
+    "full_name": "Jane Smith",
+    "email": "jane@example.com",
+    "message": "Hello!"
+  }
+}</code></pre>
+      <p>Use this to integrate with Zapier, Make, Slack, or any HTTP endpoint.</p>
+
+      <h3>3. CMS Action (Pro)</h3>
+      <p>Actions are reusable workflow steps defined in <a href="#/actions">Actions</a>. A single action can chain
+        multiple steps: update a field, move an entry to another collection, send an email, call a webhook, or
+        delete an entry.</p>
+      <p>To wire an Action to a form:</p>
+      <ol>
+        <li>Create an Action in <a href="#/actions">Actions</a> targeting the same collection as your form.</li>
+        <li>Open the form in <a href="#/forms">Forms</a> → <strong>Actions</strong> tab → <strong>CMS Action</strong>
+          card.</li>
+        <li>Select the Action from the dropdown and save.</li>
+      </ol>
+      <p>The Action runs server-side, after the entry is saved. If it fails (e.g. MongoDB is not configured),
+        the submission is still stored - the action failure is non-fatal and logged as a warning.</p>
+
+      <h3>4. Success message vs. redirect</h3>
+      <p>After a successful submission the visitor sees one of two things:</p>
+      <ul>
+        <li><strong>Inline success message</strong> - the form is replaced by the text set in
+          <em>Settings → Success Message</em>. Good for simple acknowledgements.</li>
+        <li><strong>Page redirect</strong> - the visitor is sent to the URL set in
+          <em>Settings → Success Redirect URL</em>. Good for registration flows, checkouts, or when you want
+          a full thank-you page with additional content. <strong>Takes priority</strong> if both are set.</li>
+      </ul>
+      <p>Example: set <em>Success Redirect URL</em> to <code>/thank-you</code> and create a <code>thank-you.md</code>
+        page in the CMS with any content you like.</p>
+
+      <h3>Execution order</h3>
+      <p>On every submission, the pipeline runs in this fixed order:</p>
+      <ol>
+        <li>Validate fields + honeypot + rate limit</li>
+        <li>Store entry to collection</li>
+        <li>Send email (if enabled)</li>
+        <li>Call webhook (if enabled)</li>
+        <li>Execute CMS Action (if set)</li>
+        <li>Return success response → client redirects or shows message</li>
+      </ol>
+      <p>Steps 3-5 are non-fatal: a failure in any of them is logged as a warning but does not prevent the
+        submission from being stored or the success response from being returned.</p>
+
+    </div>
+  </div>
+```
+
+- [ ] **Step 2: Commit**
+
+```bash
+git add admin/js/templates/tutorials.html
+git commit -m "docs: add form follow-up tutorial to admin tutorials page"
+```
+
+---
+
+### Task 7: Add documentation entry to documentation.html
+
+**Files:**
+
+- Modify: `admin/js/templates/documentation.html`
+
+Find the section that covers Forms (search for `forms` or `submission` in the file). Add a concise reference block for
+the two new fields.
+
+- [ ] **Step 1: Locate the Forms section**
+
+Search for the Forms card heading in `documentation.html`:
+
+```bash
+grep -n "Forms\|submission\|Submit" admin/js/templates/documentation.html | head -20
+```
+
+- [ ] **Step 2: Add new fields reference**
+
+Within the Forms documentation card body, add after the existing content:
+
+```html
+      <h3>Form follow-up</h3>
+      <p>Two optional settings control what happens after a submission is stored:</p>
+      <table class="table" style="font-size:.9rem;">
+        <thead>
+          <tr><th>Field</th><th>Where</th><th>Description</th></tr>
+        </thead>
+        <tbody>
+          <tr>
+            <td><code>successMessage</code></td>
+            <td>Settings tab</td>
+            <td>Text shown inline after submission (replaces the form). Default: "Thank you for your submission."</td>
+          </tr>
+          <tr>
+            <td><code>successRedirect</code></td>
+            <td>Settings tab</td>
+            <td>URL to redirect the visitor on success. Takes priority over <code>successMessage</code> if set.</td>
+          </tr>
+          <tr>
+            <td><code>actionSlug</code></td>
+            <td>Actions tab → CMS Action</td>
+            <td>Slug of a CMS Action to execute after the entry is stored. Requires Pro (MongoDB). Non-fatal on failure.</td>
+          </tr>
+        </tbody>
+      </table>
+      <p>For the full walkthrough, see the
+        <a href="#/tutorials">Tutorials → Form Follow-Up: Notifications &amp; Actions</a> tutorial.</p>
+```
+
+- [ ] **Step 3: Commit**
+
+```bash
+git add admin/js/templates/documentation.html
+git commit -m "docs: add form follow-up fields reference to documentation"
+```
+
+---
+
+## Verification
+
+After a server restart, test the full flow:
+
+```bash
+# 1. Submit the enquiries form via curl (no auth needed)
+curl -s -X POST http://localhost:4096/api/forms/submit/enquiries \
+  -H 'Content-Type: application/json' \
+  -d '{"full_name":"Test User","email":"test@example.com","message":"Hello"}'
+
+# Expected: {"ok":true,"message":"...","redirect":"/thank-you"}
+
+# 2. Confirm the entry was stored
+TOKEN=$(curl -s -X POST http://localhost:4096/api/auth/login \
+  -H 'Content-Type: application/json' \
+  -d '{"email":"darryl@dwit.uk","password":"YOUR_PASSWORD"}' | python3 -c "import sys,json; print(json.load(sys.stdin)['token'])")
+curl -s http://localhost:4096/api/forms/enquiries/submissions \
+  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool | head -20
+
+# 3. Verify the thank-you page renders
+curl -s http://localhost:4096/thank-you | grep -o '<title>[^<]*</title>'
+```
+
+**Manual browser test:**
+
+1. Visit `/contact` - submit the enquiries form
+2. Should redirect to `/thank-you`
+3. Open the form editor for `enquiries` in the admin - verify the Success Redirect field shows `/thank-you`
+4. Admin tutorials page (`#/tutorials`) - verify the new card appears and is collapsible
+5. Admin documentation page (`#/documentation`) - verify the Forms section shows the new table