domma-cms 0.25.14 → 0.25.16

package/admin/js/templates/docs/tutorial-plugin.html

@@ -0,0 +1,234 @@
+<div class="view-header">
+  <h1><span data-icon="document"></span> Writing a Plugin</h1>
+  <a href="#/tutorials" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> All tutorials</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+      <p>Plugins live in the <code>plugins/</code> directory. Each plugin is a self-contained folder with
+        three required files and optional <code>admin/</code> and <code>public/</code> subdirectories.</p>
+
+      <h3>Directory structure</h3>
+      <pre class="code-block"><code>plugins/
+  my-plugin/
+    plugin.json          ← manifest (required)
+    plugin.js            ← Fastify plugin (required)
+    config.js            ← settings defaults (required)
+    admin/
+      views/
+        my-view.js       ← admin SPA view (optional)
+      templates/
+        my-view.html     ← view template (optional)
+    public/
+      inject-head.html   ← injected into &lt;head&gt; on every page (optional)
+      inject-body.html   ← injected before &lt;/body&gt; on every page (optional)
+    data/                ← plugin data store (optional, not publicly served)</code></pre>
+
+      <hr>
+
+      <h3>1. plugin.json — the manifest</h3>
+      <p>All fields below are <strong>required</strong>. Missing any will cause the plugin to be skipped on
+        startup with a warning in the server log.</p>
+      <pre class="code-block"><code>{
+    "name": "my-plugin",
+    "displayName": "My Plugin",
+    "version": "1.0.0",
+    "description": "A short description shown on the Plugins page.",
+    "author": "Your Name",
+    "date": "2026-03-01",
+    "icon": "star"
+}</code></pre>
+
+      <p>Optional fields:</p>
+      <table class="table table-sm">
+        <thead>
+        <tr>
+          <th>Field</th>
+          <th>Type</th>
+          <th>Description</th>
+        </tr>
+        </thead>
+        <tbody>
+        <tr>
+          <td><code>inject.head</code></td>
+          <td>string</td>
+          <td>Path (relative to plugin root) to an HTML snippet injected into <code>&lt;head&gt;</code>.</td>
+        </tr>
+        <tr>
+          <td><code>inject.bodyEnd</code></td>
+          <td>string</td>
+          <td>Path to an HTML snippet injected before <code>&lt;/body&gt;</code>.</td>
+        </tr>
+        <tr>
+          <td><code>admin.sidebar</code></td>
+          <td>array</td>
+          <td>Sidebar items to add to the admin panel.</td>
+        </tr>
+        <tr>
+          <td><code>admin.routes</code></td>
+          <td>array</td>
+          <td>SPA routes to register in the admin router.</td>
+        </tr>
+        <tr>
+          <td><code>admin.views</code></td>
+          <td>object</td>
+          <td>View modules to dynamically import into the admin SPA.</td>
+        </tr>
+        </tbody>
+      </table>
+
+      <hr>
+
+      <h3>2. plugin.js — the Fastify plugin</h3>
+      <p>This is the server-side entry point. It must export a default <strong>async function</strong> that
+        Fastify will call with <code>(fastify, options)</code>.</p>
+      <p>The CMS injects auth middleware through <code>options.auth</code> — always destructure from there
+        rather than importing directly.</p>
+
+      <pre class="code-block"><code>import { getPluginSettings, savePluginState } from '../../server/services/plugins.js';
+
+export default async function myPlugin(fastify, options) {
+    const { authenticate, requireAdmin } = options.auth;
+
+    // Public endpoint — no auth needed
+    fastify.get('/hello', async () => {
+        return { message: 'Hello from my plugin!' };
+    });
+
+    // Admin-only endpoint
+    fastify.get('/settings', { preHandler: [authenticate, requireAdmin] }, async () => {
+        return getPluginSettings('my-plugin');
+    });
+
+    fastify.put('/settings', { preHandler: [authenticate, requireAdmin] }, async (request) => {
+        savePluginState('my-plugin', { settings: request.body });
+        return { ok: true };
+    });
+}</code></pre>
+
+      <p>Routes are registered under the prefix <code>/api/plugins/{name}</code> automatically. You do not
+        set the prefix yourself — it is always locked to your plugin's directory name.</p>
+
+      <hr>
+
+      <h3>3. config.js — settings defaults</h3>
+      <p>Export a plain object of default settings. These are merged with any user overrides stored in
+        <code>config/plugins.json</code> when <code>getPluginSettings()</code> is called.</p>
+
+      <pre class="code-block"><code>export default {
+    greeting: 'Hello, world!',
+    enableFeature: true,
+    maxItems: 10
+};</code></pre>
+
+      <p><code>config.js</code> is only loaded for <strong>enabled</strong> plugins. Side-effect code here
+        will not run for disabled plugins.</p>
+
+      <hr>
+
+      <h3>4. Admin views (optional)</h3>
+      <p>To add a page to the admin panel, declare the route and view in <code>plugin.json</code>:</p>
+
+      <pre class="code-block"><code>"admin": {
+    "sidebar": [
+        {
+            "id": "my-plugin",
+            "text": "My Plugin",
+            "icon": "star",
+            "url": "#/plugins/my-plugin",
+            "section": "#/plugins/my-plugin"
+        }
+    ],
+    "routes": [
+        {
+            "path": "/plugins/my-plugin",
+            "view": "plugin-my-plugin",
+            "title": "My Plugin - Domma CMS"
+        }
+    ],
+    "views": {
+        "plugin-my-plugin": {
+            "entry": "my-plugin/admin/views/my-view.js",
+            "exportName": "myPluginView"
+        }
+    }
+}</code></pre>
+
+      <p>The view file follows the standard Domma view pattern — a <code>templateUrl</code> and an
+        <code>onMount($container)</code> function:</p>
+
+      <pre class="code-block"><code>// admin/views/my-view.js
+export const myPluginView = {
+    templateUrl: '/plugins/my-plugin/admin/templates/my-view.html',
+
+    async onMount($container) {
+        const res = await fetch('/api/plugins/my-plugin/settings', {
+            headers: { 'Authorization': 'Bearer ' + (S.get('auth_token') || '') }
+        });
+        const settings = await res.json();
+
+        $container.find('#greeting').text(settings.greeting);
+        Domma.icons.scan();
+    }
+};</code></pre>
+
+      <p>The template is a plain HTML fragment (no <code>&lt;html&gt;</code> wrapper). Use the same card and
+        form patterns as the rest of the admin panel:</p>
+
+      <pre class="code-block"><code>&lt;!-- admin/templates/my-view.html --&gt;
+&lt;div class="view-header"&gt;
+    &lt;h1&gt;&lt;span data-icon="star"&gt;&lt;/span&gt; My Plugin&lt;/h1&gt;
+&lt;/div&gt;
+
+&lt;div class="card"&gt;
+    &lt;div class="card-body"&gt;
+        &lt;p id="greeting"&gt;Loading…&lt;/p&gt;
+    &lt;/div&gt;
+&lt;/div&gt;</code></pre>
+
+      <hr>
+
+      <h3>5. Injection snippets (optional)</h3>
+      <p>HTML snippets declared in <code>inject.head</code> and <code>inject.bodyEnd</code> are read from
+        the plugin's <code>public/</code> directory and inserted into every public page. Use this for
+        analytics scripts, stylesheets, or widgets.</p>
+
+      <pre class="code-block"><code>&lt;!-- public/inject-body.html --&gt;
+&lt;script&gt;
+(function () {
+    // This runs on every public page
+    fetch('/api/plugins/my-plugin/hello')
+        .then(r => r.json())
+        .then(d => console.log(d.message));
+})();
+&lt;/script&gt;</code></pre>
+
+      <p>Snippet paths are validated — they must stay within the plugin's own directory. Paths containing
+        <code>..</code> are blocked.</p>
+
+      <hr>
+
+      <h3>6. Registering and testing</h3>
+      <ol>
+        <li>Create the <code>plugins/my-plugin/</code> directory with all three required files.</li>
+        <li>Restart the server — you should see <code>[plugins] Loaded N plugins: …, my-plugin</code> in
+          the log.
+        </li>
+        <li>Go to the <a href="#/plugins">Plugins page</a> and enable your plugin.</li>
+        <li>Restart the server again to register the routes.</li>
+        <li>Verify your endpoint: <code>GET /api/plugins/my-plugin/hello</code></li>
+      </ol>
+
+      <p class="text-muted" style="font-size:.9rem">Tip: use <code>npm run dev</code> during development —
+        the server restarts automatically on file changes.</p>
+
+      <hr>
+      <p class="text-muted" style="font-size:.9rem;">
+        Next: <a href="#/tutorials/forms">Form Follow-Up →</a>
+      </p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/usage-actions.html

@@ -0,0 +1,122 @@
+<div class="view-header">
+  <h1><span data-icon="book"></span> Actions</h1>
+  <a href="#/documentation" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> All usage topics</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>Actions are admin-designed sequential workflow operations triggered against individual collection
+                      entries. When an action is assigned to a collection, a trigger button appears per row in the
+                      entry list. Actions require a MongoDB connection (pro mode).</p>
+
+                  <h3>Creating an Action</h3>
+                  <ol>
+                      <li>Navigate to <strong>Data → Actions</strong> and click <strong>New Action</strong>.</li>
+                      <li><strong>General tab</strong> — enter a title and select the target collection.</li>
+                      <li><strong>Trigger tab</strong> — configure the button label, icon, and optional confirmation
+                          message.
+                      </li>
+                      <li><strong>Steps tab</strong> — add steps in order. Each step runs sequentially; if one fails the
+                          action stops.
+                      </li>
+                      <li><strong>Access tab</strong> — select which roles can trigger this action.</li>
+                      <li>Click <strong>Save Action</strong>. The button will appear on the collection's entry list.
+                      </li>
+                  </ol>
+
+                  <h3>Phase 1 Step Types</h3>
+                  <table class="table table-sm">
+                      <thead>
+                      <tr>
+                          <th>Step</th>
+                          <th>What it does</th>
+                          <th>Config fields</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>updateField</code></td>
+                          <td>Set a field on the entry to a new value</td>
+                          <td><code>field</code>, <code>value</code></td>
+                      </tr>
+                      <tr>
+                          <td><code>deleteEntry</code></td>
+                          <td>Permanently delete the entry</td>
+                          <td>None</td>
+                      </tr>
+                      <tr>
+                          <td><code>moveToCollection</code></td>
+                          <td>Create the entry in a target collection then delete it from the source</td>
+                          <td><code>targetCollection</code></td>
+                      </tr>
+                      <tr>
+                          <td><code>webhook</code></td>
+                          <td>HTTP request to an external URL</td>
+                          <td><code>url</code>, <code>method</code>, <code>body</code> (JSON)</td>
+                      </tr>
+                      <tr>
+                          <td><code>email</code></td>
+                          <td>Send an email via the configured SMTP transport</td>
+                          <td><code>to</code>, <code>subject</code>, <code>template</code></td>
+                      </tr>
+                      </tbody>
+                  </table>
+
+                  <h3>Template Variables</h3>
+                  <p>Step config fields support <code>{{variable}}</code> interpolation:</p>
+                  <table class="table table-sm">
+                      <thead>
+                      <tr>
+                          <th>Variable</th>
+                          <th>Resolves to</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>{{entry.data.fieldName}}</code></td>
+                          <td>A field value from the current entry</td>
+                      </tr>
+                      <tr>
+                          <td><code>{{entry.id}}</code></td>
+                          <td>The entry's ID</td>
+                      </tr>
+                      <tr>
+                          <td><code>{{now}}</code></td>
+                          <td>Current timestamp (ISO 8601)</td>
+                      </tr>
+                      <tr>
+                          <td><code>{{user.name}}</code></td>
+                          <td>Name of the user who triggered the action</td>
+                      </tr>
+                      <tr>
+                          <td><code>{{user.email}}</code></td>
+                          <td>Email of the triggering user</td>
+                      </tr>
+                      <tr>
+                          <td><code>{{env.CMS_PUBLIC_*}}</code></td>
+                          <td>Environment variables prefixed <code>CMS_PUBLIC_</code> only</td>
+                      </tr>
+                      </tbody>
+                  </table>
+                  <p><strong>Example</strong> — approve an application and notify by email:</p>
+                  <pre class="code-block"><code>Step 1: updateField  field=status      value=approved
+Step 2: updateField  field=approvedAt  value={{now}}
+Step 3: email        to={{entry.data.email}}
+                     subject=Your application has been approved
+                     template=Congratulations {{entry.data.name}}, your application is approved.</code></pre>
+
+                  <h3>Partial Execution</h3>
+                  <p>Actions are <strong>not transactional</strong>. If a step fails, the action stops and returns the
+                      number of steps completed so far (<code>stepsCompleted</code>). Steps that already ran are
+                      <strong>not rolled back</strong>. Design step order with this in mind — put irreversible steps
+                      (delete, email) last.</p>
+
+                  <h3>After a deleteEntry step</h3>
+                  <p>If an action contains a <code>deleteEntry</code> step, subsequent steps will fail because the entry
+                      no longer exists. Place <code>deleteEntry</code> as the last step.</p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/usage-cta-shortcode.html

@@ -0,0 +1,124 @@
+<div class="view-header">
+  <h1><span data-icon="book"></span> CTA Shortcode</h1>
+  <a href="#/documentation" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> All usage topics</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>The <code>[cta]</code> shortcode places an action-trigger button in any public page. Clicking it
+                      calls
+                      <code>POST /api/actions/:slug/public</code> with the entry ID, using the logged-in user's JWT.
+                      If the user is not logged in, a warning toast is shown instead.</p>
+
+                  <h3>Syntax &amp; Attributes</h3>
+                  <p><strong>Wrapping form:</strong></p>
+                  <pre class="code-block"><code>[cta action="slug" entry="entry-id" icon="check" confirm="Are you sure?"]Button label[/cta]</code></pre>
+                  <p><strong>Self-closing form:</strong></p>
+                  <pre class="code-block"><code>[cta action="slug" entry="entry-id" label="Button label" /]</code></pre>
+                  <table class="table table-sm" style="margin-top:1rem;">
+                      <thead>
+                      <tr>
+                          <th>Attribute</th>
+                          <th>Required</th>
+                          <th>Default</th>
+                          <th>Description</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>action</code></td>
+                          <td>Yes</td>
+                          <td>—</td>
+                          <td>Action slug</td>
+                      </tr>
+                      <tr>
+                          <td><code>entry</code></td>
+                          <td>Yes</td>
+                          <td>—</td>
+                          <td>Entry UUID to act on</td>
+                      </tr>
+                      <tr>
+                          <td><code>label</code></td>
+                          <td>No</td>
+                          <td><code>"Run"</code></td>
+                          <td>Button text (self-closing only)</td>
+                      </tr>
+                      <tr>
+                          <td><code>style</code></td>
+                          <td>No</td>
+                          <td><code>"primary"</code></td>
+                          <td>primary · secondary · ghost · danger</td>
+                      </tr>
+                      <tr>
+                          <td><code>icon</code></td>
+                          <td>No</td>
+                          <td>—</td>
+                          <td>Domma icon name</td>
+                      </tr>
+                      <tr>
+                          <td><code>size</code></td>
+                          <td>No</td>
+                          <td>—</td>
+                          <td>sm · md · lg</td>
+                      </tr>
+                      <tr>
+                          <td><code>confirm</code></td>
+                          <td>No</td>
+                          <td>—</td>
+                          <td>Confirmation prompt before executing</td>
+                      </tr>
+                      </tbody>
+                  </table>
+
+                  <h3>Collection Integration</h3>
+                  <p>Add per-entry buttons to any <code>[collection]</code> shortcode:</p>
+                  <pre class="code-block"><code>[collection slug="applications" display="cards" title-field="name"
+  cta="approve-application"
+  cta-label="Approve"
+  cta-icon="check"
+  cta-style="primary"
+  cta-confirm="Approve this application?" /]</code></pre>
+                  <table class="table table-sm" style="margin-top:1rem;">
+                      <thead>
+                      <tr>
+                          <th>Attribute</th>
+                          <th>Default</th>
+                          <th>Description</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>cta</code></td>
+                          <td>—</td>
+                          <td>Action slug — enables per-entry buttons</td>
+                      </tr>
+                      <tr>
+                          <td><code>cta-label</code></td>
+                          <td><code>"Run"</code></td>
+                          <td>Button label</td>
+                      </tr>
+                      <tr>
+                          <td><code>cta-icon</code></td>
+                          <td>—</td>
+                          <td>Domma icon name</td>
+                      </tr>
+                      <tr>
+                          <td><code>cta-style</code></td>
+                          <td><code>"primary"</code></td>
+                          <td>Button variant</td>
+                      </tr>
+                      <tr>
+                          <td><code>cta-confirm</code></td>
+                          <td>—</td>
+                          <td>Confirmation prompt</td>
+                      </tr>
+                      </tbody>
+                  </table>
+                  <p>All three display modes support CTA buttons: <strong>cards</strong> (card footer),
+                      <strong>list</strong> (inline), <strong>table</strong> (dedicated column).</p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/usage-dconfig.html

@@ -0,0 +1,148 @@
+<div class="view-header">
+  <h1><span data-icon="book"></span> DConfig</h1>
+  <a href="#/documentation" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> All usage topics</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>DConfig lets you wire up declarative behaviour on any public page — no JavaScript required. Define
+                      event
+                      handlers and class toggles in JSON; the page runtime applies them automatically on load.</p>
+
+                  <p>DConfig can be set in two ways, and both are merged at runtime (inline shortcode wins on selector
+                      conflict):</p>
+                  <ul>
+                      <li><strong>Page editor</strong> — the <em>DConfig</em> collapsible section accepts a JSON blob
+                          stored in page
+                          frontmatter and injected as <code>window.__CMS_DCONFIG__</code>.
+                      </li>
+                      <li><strong>Inline shortcode</strong> — place one or more <code>[dconfig]…[/dconfig]</code> blocks
+                          directly in
+                          the page body Markdown.
+                      </li>
+                  </ul>
+
+                  <h3>Schema</h3>
+                  <pre class="code-block"><code>{
+  "#selector": {
+    "events": {
+      "eventName": {
+        "target": "#target-selector",
+        "action": "value"
+      }
+    }
+  }
+}</code></pre>
+
+                  <p>Multiple selectors and multiple event types can appear in a single config block.</p>
+
+                  <h3>Supported events</h3>
+                  <table class="table table-sm">
+                      <thead>
+                      <tr>
+                          <th>Event</th>
+                          <th>Description</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>click</code></td>
+                          <td>Fires when the selector element is clicked.</td>
+                      </tr>
+                      </tbody>
+                  </table>
+
+                  <h3>Supported actions</h3>
+                  <table class="table table-sm">
+                      <thead>
+                      <tr>
+                          <th>Action key</th>
+                          <th>Value type</th>
+                          <th>Description</th>
+                      </tr>
+                      </thead>
+                      <tbody>
+                      <tr>
+                          <td><code>toggleClass</code></td>
+                          <td><code>string</code></td>
+                          <td>Adds the class if absent, removes it if present, on the <code>target</code> element.
+                              Typical use:
+                              show/hide content with a <code>hidden</code> class.
+                          </td>
+                      </tr>
+                      </tbody>
+                  </table>
+
+                  <p><em>Additional actions (addClass, removeClass, setAttribute, scroll-to) are planned for future
+                      releases.</em></p>
+
+                  <h3>Targeting shortcode elements with <code>id</code></h3>
+                  <p>All shortcodes support an <code>id</code> attribute, which is written directly onto the generated
+                      element.
+                      Use this instead of raw HTML when you want DConfig to target a card, column, or grid:</p>
+                  <pre class="code-block"><code>[card id="my-panel" title="Hidden Details"]
+Content goes here.
+[/card]
+
+[dconfig]
+{
+  "#my-btn": {
+    "events": {
+      "click": { "target": "#my-panel", "toggleClass": "hidden" }
+    }
+  }
+}
+[/dconfig]</code></pre>
+                  <p>Supported on: <code>[card]</code>, <code>[col]</code>, <code>[row]</code>, <code>[grid]</code>.</p>
+
+                  <h3>Using the <code>[dconfig]</code> shortcode</h3>
+                  <pre class="code-block"><code>[dconfig]
+{
+  "#my-btn": {
+    "events": {
+      "click": { "target": "#my-panel", "toggleClass": "hidden" }
+    }
+  }
+}
+[/dconfig]
+
+&lt;button id="my-btn" class="btn btn-primary"&gt;Toggle&lt;/button&gt;
+
+&lt;div id="my-panel" class="card hidden"&gt;
+  &lt;div class="card-body"&gt;Hidden content.&lt;/div&gt;
+&lt;/div&gt;</code></pre>
+
+                  <h3>Multiple selectors</h3>
+                  <p>Any number of selectors can appear in one block. Selectors are matched with
+                      <code>document.querySelector</code> — use IDs, classes, or attribute selectors.</p>
+                  <pre class="code-block"><code>[dconfig]
+{
+  "#show-btn": {
+    "events": {
+      "click": { "target": "#panel", "toggleClass": "hidden" }
+    }
+  },
+  "#hide-btn": {
+    "events": {
+      "click": { "target": "#panel", "toggleClass": "hidden" }
+    }
+  }
+}
+[/dconfig]</code></pre>
+
+                  <h3>Using the page editor DConfig section</h3>
+                  <p>The same JSON (without the shortcode tags) can be pasted directly into the <em>DConfig</em> card in
+                      the page
+                      editor. This is useful when the config should apply to the whole page without appearing in the
+                      body content.
+                      Inline <code>[dconfig]</code> shortcodes are applied last and will win on any shared selector key.
+                  </p>
+
+                  <p>See live demos on the <a href="/resources/interactive" target="_blank">Interactive Resources
+                      page</a>.</p>
+
+    </div>
+  </div>
+</div>

package/admin/js/templates/docs/usage-media.html

@@ -0,0 +1,25 @@
+<div class="view-header">
+  <h1><span data-icon="book"></span> Media</h1>
+  <a href="#/documentation" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> All usage topics</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+
+<p>Media files are stored in <code>content/media/</code> and served publicly at <code>/media/{filename}</code>.
+                  </p>
+
+                  <h3>Using media in pages</h3>
+                  <p>Reference uploaded files by their public URL in Markdown:</p>
+                  <pre class="code-block"><code>![Alt text](/media/my-image.jpg)
+
+&lt;img src="/media/my-image.jpg" alt="Alt text"&gt;</code></pre>
+
+                  <h3>Upload limits</h3>
+                  <p>The maximum file size is configured in <code>config/server.json</code> under <code>uploads.maxFileSize</code>
+                      (bytes). Default is 10 MB.</p>
+
+    </div>
+  </div>
+</div>