domma-cms 0.92.1 → 0.94.0

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

@@ -8,40 +8,51 @@
     <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>
+        three required files and optional <code>admin/</code>, <code>public/</code> and <code>docs/</code>
+        subdirectories.</p>
+      <p>The quickest start is <strong>New plugin</strong> in the banner of <a href="#/plugins">System &gt;
+        Plugins</a> (the Marketplace screen). It copies the built-in template into <code>plugins/&lt;slug&gt;/</code>
+        with a server entry, config defaults, a wired admin view and a <code>CLAUDE.md</code>, switched on. Restart
+        the server to activate it. The rest of this page explains what those files do.</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)
+    plugin.json          - manifest (required)
+    plugin.js            - Fastify plugin (required)
+    config.js            - settings defaults (required)
     admin/
       views/
-        my-view.js       ← admin SPA view (optional)
+        index.js         - admin view (optional)
       templates/
-        my-view.html     ← view template (optional)
+        index.html       - view template (optional)
+      css/
+        index.css        - admin styles (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>
+      inject-head.html   - injected into &lt;head&gt; on every page (optional)
+      inject-body.html   - injected before &lt;/body&gt; on every page (optional)
+    docs/
+      guide.md           - user guide under Documentation &gt; Plugins (optional)
+    data/                - plugin data store (optional, never served)</code></pre>
+      <p>Only <code>admin/</code> and <code>public/</code> are served over HTTP; <code>plugin.js</code>,
+        <code>config.js</code> and <code>data/</code> never are.</p>
 
       <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>
+        startup with a warning in the server log. <code>name</code> must match the folder name.</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.",
+    "description": "A short description shown in the Marketplace.",
     "author": "Your Name",
     "date": "2026-03-01",
     "icon": "star"
 }</code></pre>
 
-      <p>Optional fields:</p>
+      <p>Common optional fields:</p>
       <table class="table table-sm">
         <thead>
         <tr>
@@ -56,6 +67,12 @@
           <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.headLate</code></td>
+          <td>string</td>
+          <td>A snippet injected at the end of <code>&lt;head&gt;</code>, after the site stylesheets - for CSS
+            that must win.</td>
+        </tr>
         <tr>
           <td><code>inject.bodyEnd</code></td>
           <td>string</td>
@@ -76,6 +93,44 @@
           <td>object</td>
           <td>View modules to dynamically import into the admin SPA.</td>
         </tr>
+        <tr>
+          <td><code>admin.css</code></td>
+          <td>array</td>
+          <td>Admin stylesheets loaded with the plugin's views.</td>
+        </tr>
+        <tr>
+          <td><code>permissions</code></td>
+          <td>array</td>
+          <td>Permission resources the plugin guards its routes with. They appear in the role editor;
+            <code>grant</code> gives existing roles them once.</td>
+        </tr>
+        <tr>
+          <td><code>requires</code></td>
+          <td>array</td>
+          <td>Built-in Tools (<code>contacts</code>, <code>notes</code>, <code>todo</code>, <code>analytics</code>,
+            <code>seo</code>) or plugins this one cannot work without. It is not loaded while one is off.</td>
+        </tr>
+        <tr>
+          <td><code>uses</code></td>
+          <td>object</td>
+          <td><code>{"contacts": "Invite a contact group"}</code> - Tools or plugins it works without but uses
+            when they are on. The text is what the admin is told they lose.</td>
+        </tr>
+        <tr>
+          <td><code>supersedes</code></td>
+          <td>array</td>
+          <td>Plugins (or built-in Tools) this one replaces outright, such as a Pro edition of a free plugin.</td>
+        </tr>
+        <tr>
+          <td><code>settingsSchema</code></td>
+          <td>array</td>
+          <td>Labels, types and help for the Marketplace <strong>Configure</strong> form.</td>
+        </tr>
+        <tr>
+          <td><code>minCmsVersion</code></td>
+          <td>string</td>
+          <td>The oldest Domma CMS the plugin works on. Install and update are refused on an older CMS.</td>
+        </tr>
         </tbody>
       </table>
 
@@ -84,38 +139,48 @@
       <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>
+      <p>The CMS hands you auth middleware in <code>options.auth</code> (<code>authenticate</code>,
+        <code>requireAdmin</code>, <code>requirePermission</code>, <code>requireRole</code>,
+        <code>requireVisibility</code>), extension points in <code>options.hooks</code> (shortcodes, transforms,
+        sidebar items, notifications, <code>registerComponent</code> and more) and the merged settings in
+        <code>options.settings</code>. Always take them from there rather than importing the middleware 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
+    // Admin-only endpoint (role levels 0 and 1)
     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 };
     });
+}
+// Optional: runs once each time the plugin is switched on, not at install.
+export async function onEnable({ fastify, services, hooks }) {
+    // Create collections, pages or forms here if needed.
+}
+// Optional: runs when it is switched off, and before an uninstall (uninstall: true).
+export async function onDisable({ fastify, services, hooks, uninstall }) {
 }</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>
+      <p>Routes are registered under the prefix <code>/api/plugins/{name}</code> automatically - write
+        <code>'/hello'</code>, not the full path. The prefix is always locked to your plugin's directory name.</p>
+      <p>For your own screens, prefer <code>requirePermission('my-plugin', 'read')</code> with a permission
+        declared in <code>plugin.json</code> over <code>requireAdmin</code>: the site owner can then give it to any
+        role in <a href="#/roles">System &gt; Roles</a>.</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>
+      <p>Export a plain object of default settings. These are merged with any overrides stored in
+        <code>config/plugins.json</code> when <code>getPluginSettings()</code> is called. The site owner changes
+        them with <strong>Configure</strong> on the plugin in the Marketplace.</p>
 
       <pre class="code-block"><code>export default {
     greeting: 'Hello, world!',
@@ -150,58 +215,55 @@ export default async function myPlugin(fastify, options) {
     ],
     "views": {
         "plugin-my-plugin": {
-            "entry": "my-plugin/admin/views/my-view.js",
+            "entry": "my-plugin/admin/views/index.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>
+        <code>onMount($container)</code> function. Call your API with <code>H.get</code> / <code>H.post</code>,
+        which add the sign-in header and refresh the token for you - do not hand-build a Bearer header with
+        <code>fetch()</code>:</p>
 
-      <pre class="code-block"><code>// admin/views/my-view.js
+      <pre class="code-block"><code>// admin/views/index.js
 export const myPluginView = {
-    templateUrl: '/plugins/my-plugin/admin/templates/my-view.html',
-
+    templateUrl: '/plugins/my-plugin/admin/templates/index.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();
-
+        const res = await H.get('/api/plugins/my-plugin/settings');
+        const settings = res.data ?? res;
         $container.find('#greeting').text(settings.greeting);
-        Domma.icons.scan();
+        I.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;
+      <p>The template is a plain HTML fragment (no <code>&lt;html&gt;</code> wrapper) using Domma classes
+        (<code>card</code>, <code>btn</code>, <code>form-input</code>). The admin already wraps every plugin view in
+        a banner with the plugin's name, version and licence, so do not draw your own page heading:</p>
 
+      <pre class="code-block"><code>&lt;!-- admin/templates/index.html --&gt;
 &lt;div class="card"&gt;
     &lt;div class="card-body"&gt;
-        &lt;p id="greeting"&gt;Loading…&lt;/p&gt;
+        &lt;p id="greeting"&gt;Loading...&lt;/p&gt;
     &lt;/div&gt;
 &lt;/div&gt;</code></pre>
+      <p>Files under <code>admin/</code> are fetched by the browser, so a hard refresh of the admin picks up a
+        change without a restart.</p>
 
       <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>
+      <p>HTML snippets declared in <code>inject.head</code>, <code>inject.headLate</code> and
+        <code>inject.bodyEnd</code> are read from the plugin's folder and inserted into every public page. Use
+        this for analytics scripts, stylesheets, or widgets. They are read once at start-up.</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));
+        .then(r =&gt; r.json())
+        .then(d =&gt; console.log(d.message));
 })();
 &lt;/script&gt;</code></pre>
 
@@ -210,23 +272,37 @@ export const myPluginView = {
 
       <hr>
 
-      <h3>6. Registering and testing</h3>
+      <h3>6. User guide (optional)</h3>
+      <p>Markdown files in the plugin's <code>docs/</code> folder become pages under <strong>Documentation &gt;
+        Plugins</strong> while the plugin is loaded, shown only to users who can use the plugin.
+        <code>guide.md</code> is the first page; further files become tabs. Start with <code>##</code> sections,
+        not a top-level heading, and write for site owners.</p>
+
+      <hr>
+
+      <h3>7. Switching it on 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>Create the <code>plugins/my-plugin/</code> directory with all three required files (or use
+          <strong>New plugin</strong>, which does this and switches it on).</li>
+        <li>Open <a href="#/plugins">System &gt; Plugins</a>. A plugin you made by hand is listed, switched off.
+          Right-click it (or use its menu) and choose <strong>Switch on</strong>. Its <code>onEnable</code> runs
+          now.</li>
+        <li>The server restarts by itself to load the plugin's routes and screens, where a supervisor (the
+          fleet manager or pm2) will bring it back and <code>restartOnPluginToggle</code> is not
+          <code>false</code> in <code>config/server.json</code>. Otherwise restart it yourself. The log then
+          shows <code>[plugins] Loaded N plugins: ..., my-plugin</code>.</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>
+        the server restarts automatically on file changes. Server-side files (<code>plugin.js</code>,
+        <code>config.js</code>, <code>plugin.json</code>, snippets) only apply after a restart; the in-admin code
+        editor (<strong>View source</strong> on the plugin) has a Restart server button. For the full reference see
+        <code>docs/plugin-development.md</code> in the Domma CMS package.</p>
 
       <hr>
       <p class="text-muted" style="font-size:.9rem;">
-        Next: <a href="#/tutorials/forms">Form Follow-Up →</a>
+        Next: <a href="#/tutorials/forms">Form Follow-Up</a>
       </p>
 
     </div>

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

@@ -9,24 +9,27 @@
 
 <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>
+                      entry list. Actions need a MongoDB connection, which is a Pro feature: without one, Data &gt; Actions
+                      says so and nothing can be run.</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><strong>Trigger tab</strong> - the button label, icon and optional confirmation message.
+                          Manual (a button) is the only trigger. An optional <strong>transition</strong> makes the
+                          action a workflow step - see below.
                       </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><strong>Access tab</strong> - which roles can run the action, and an optional row-level
+                          rule. See "Who can run an action" below.</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>
+                  <h3>Step Types</h3>
                   <table class="table table-sm">
                       <thead>
                       <tr>
@@ -51,6 +54,11 @@
                           <td>Create the entry in a target collection then delete it from the source</td>
                           <td><code>targetCollection</code></td>
                       </tr>
+                      <tr>
+                          <td><code>createInCollection</code></td>
+                          <td>Create a new entry in another collection, leaving the source entry as it is (a log line, a related record)</td>
+                          <td><code>targetCollection</code>, <code>data</code> (JSON object of field values), <code>createdBy</code> (optional; defaults to the person running the action)</td>
+                      </tr>
                       <tr>
                           <td><code>webhook</code></td>
                           <td>HTTP request to an external URL</td>
@@ -70,7 +78,7 @@
                   </table>
 
                   <h3>Template Variables</h3>
-                  <p>Step config fields support <code>{{variable}}</code> interpolation:</p>
+                  <p>Step config fields support <code>&#123;&#123;variable&#125;&#125;</code> interpolation:</p>
                   <table class="table table-sm">
                       <thead>
                       <tr>
@@ -80,43 +88,81 @@
                       </thead>
                       <tbody>
                       <tr>
-                          <td><code>{{entry.data.fieldName}}</code></td>
+                          <td><code>&#123;&#123;entry.data.fieldName&#125;&#125;</code></td>
                           <td>A field value from the current entry</td>
                       </tr>
                       <tr>
-                          <td><code>{{entry.id}}</code></td>
+                          <td><code>&#123;&#123;entry.id&#125;&#125;</code></td>
                           <td>The entry's ID</td>
                       </tr>
                       <tr>
-                          <td><code>{{now}}</code></td>
+                          <td><code>&#123;&#123;now&#125;&#125;</code></td>
                           <td>Current timestamp (ISO 8601)</td>
                       </tr>
                       <tr>
-                          <td><code>{{user.name}}</code></td>
+                          <td><code>&#123;&#123;user.id&#125;&#125;</code></td>
+                          <td>ID of the user who triggered the action</td>
+                      </tr>
+                      <tr>
+                          <td><code>&#123;&#123;user.name&#125;&#125;</code></td>
                           <td>Name of the user who triggered the action</td>
                       </tr>
                       <tr>
-                          <td><code>{{user.email}}</code></td>
+                          <td><code>&#123;&#123;user.email&#125;&#125;</code></td>
                           <td>Email of the triggering user</td>
                       </tr>
                       <tr>
-                          <td><code>{{env.CMS_PUBLIC_*}}</code></td>
+                          <td><code>&#123;&#123;user.role&#125;&#125;</code></td>
+                          <td>Primary role of the triggering user</td>
+                      </tr>
+                      <tr>
+                          <td><code>&#123;&#123;env.CMS_PUBLIC_*&#125;&#125;</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}}
+Step 2: updateField  field=approvedAt  value=&#123;&#123;now&#125;&#125;
+Step 3: email        to=&#123;&#123;entry.data.email&#125;&#125;
                      subject=Your application has been approved
-                     template=Congratulations {{entry.data.name}}, your application is approved.</code></pre>
+                     template=Congratulations &#123;&#123;entry.data.name&#125;&#125;, your application is approved.</code></pre>
+
+                  <h3>Who can run an action</h3>
+                  <ul>
+                      <li><strong>Any listed role is enough.</strong> Ticking <code>admin</code> and <code>hr</code>
+                          lets holders of either run it, and everyone more senior than either - the same ladder as
+                          page visibility. All the roles a user holds count, not just their primary one.</li>
+                      <li><strong>No roles ticked</strong> - admins only (role levels 0 and 1).</li>
+                      <li><strong>A role the site does not have</strong> (deleted or renamed) admits only the level-0
+                          role. The editor keeps it and flags it so you can fix it.</li>
+                      <li><strong>Row-level rule</strong> - Owner (entries the user created) or Field match (entries
+                          that name them in a field), checked on the server every time the action runs. The level-0
+                          role is never limited by it.</li>
+                  </ul>
+
+                  <h3>Workflows: transitions</h3>
+                  <p>Give an action a transition - a state field, the <strong>From</strong> values it may start
+                      from, and the <strong>To</strong> value - and it becomes a step in a workflow. It is offered
+                      only while the entry's field holds one of the From values; your steps (usually an Update a
+                      field step) do the actual change.</p>
+                  <p>On the public site, an interactive <code>[collection]</code> with the <code>transitions</code>
+                      attribute shows each row the buttons that apply to it right now, for the person looking -
+                      roles and the row-level rule included. Add <code>scope="mine"</code> for a "my entries" page
+                      where people move their own entries on:</p>
+                  <pre class="code-block"><code>[collection slug="applications" scope="mine" display="cards" title-field="jobTitle" paginate transitions /]</code></pre>
+                  <p>Running an action whose transition no longer applies (the entry has moved on) is refused with
+                      409 and changes nothing. From a <code>scope="mine"</code> block, a row the person did not
+                      create is refused with 403. For an action meant only for people's own entries, also give it
+                      an Owner row-level rule, so it is refused however it is called.</p>
 
                   <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>
+                  <p>See also <a href="#/docs/usage/cta-shortcode">CTA Shortcode</a> for action buttons on pages, and
+                      the <a href="#/docs/api/actions">Actions API</a>.</p>
 
                   <h3>After a deleteEntry step</h3>
                   <p>If an action contains a <code>deleteEntry</code> step, subsequent steps will fail because the entry

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

@@ -0,0 +1,108 @@
+<div class="view-header">
+  <h1><span data-icon="book"></span> Collections &amp; Forms</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>A collection is a set of entries that share the same fields - products, bookings, team members,
+                      enquiries. Collections are at <strong>Data &gt; Collections</strong>. Their entries are edited in
+                      the admin, shown on pages with <code>[collection]</code>, filled in by visitors through forms,
+                      and can be read by other systems through the API if you allow it.</p>
+
+                  <h3>Creating a collection</h3>
+                  <p>Choose <strong>New collection</strong>. The editor has four tabs:</p>
+                  <ul>
+                      <li><strong>Settings</strong> - title, slug (its id, fixed once created), project and the
+                          layout of the entry form (stacked, or a grid where each field can span columns).</li>
+                      <li><strong>Fields</strong> - what every entry holds. The editor offers text, email, phone,
+                          number, textarea, dropdown, radio buttons, single checkbox, checkbox group, date, time,
+                          URL and hidden fields. Reference (a link to an entry in another collection), file and
+                          multi-select fields exist too, but are added by editing the collection's
+                          <code>schema.json</code>.</li>
+                      <li><strong>API &amp; Export</strong> - what the public API may do (read, create, update,
+                          delete) and who may do it, which fields a read returns, and whether visitors may export
+                          what a <code>[collection]</code> display shows.</li>
+                      <li><strong>Storage</strong> - files on this server (the default) or MongoDB (Pro, when the
+                          site has a connection).</li>
+                  </ul>
+                  <p>Every collection made in the admin gets a matching form, so visitors can add entries with
+                      <code>[form name="the-slug" /]</code>.</p>
+
+                  <h3>Working with entries</h3>
+                  <p>Click a collection to see its entries. <strong>Add entry</strong>, <strong>Import</strong> and
+                      <strong>Export</strong> are in the banner. Click an entry to edit it; right-click it to see
+                      all of it, duplicate it, copy its id, run one of the collection's Actions or delete it, and
+                      right-click a value to filter by it. Dates show as dd/mm/yyyy.</p>
+                  <ul>
+                      <li><strong>Export</strong> downloads the entries as JSON or CSV.</li>
+                      <li><strong>Import</strong> takes a JSON array of entries and adds them (nothing is removed).
+                          Each entry is checked like any other save: one that fails the field rules or points a
+                          reference at an entry that does not exist is skipped and reported. Fields the collection
+                          does not have are stored as given. For backups, restores and
+                          clones of whole collections, see the Data Transfer plugin in the Marketplace.</li>
+                  </ul>
+
+                  <h3>Moving between files and MongoDB</h3>
+                  <p>Changing a collection's storage on the Storage tab asks whether to move its entries when you
+                      save. A move copies each entry exactly as it is - same id, data, created and updated dates and
+                      owner - so references, links and "my entries" pages keep working. It refuses, changing
+                      nothing, if the target already holds an entry with one of the same ids, or if MongoDB is not
+                      reachable. The old copy is set aside, never deleted (<code>data.json</code> becomes
+                      <code>data.json.bak</code>; a MongoDB collection is renamed). System collections (roles, user
+                      profiles, projects, notifications, API tokens and endpoints) always stay on files.</p>
+
+                  <h3>Showing entries on a page</h3>
+                  <pre class="code-block"><code>[collection slug="team" display="cards" columns="3" title-field="name" /]
+[collection slug="jobs" display="cards" searchable filterable="location,type" sortable where_status="open" /]
+[collection slug="applications" scope="mine" display="cards" paginate transitions /]</code></pre>
+                  <ul>
+                      <li>Eight displays: table, cards, list, accordion, timeline, carousel, listgroup and block
+                          (your own block template per entry).</li>
+                      <li><code>searchable</code>, <code>sortable</code>, <code>filterable</code> or
+                          <code>paginate</code> turn a display into the interactive <strong>Collection
+                          Browser</strong>: search, sort, a filter rail and pages.</li>
+                      <li><code>scope="mine"</code> shows signed-in visitors only the entries they created - a "my
+                          applications" or "my bookings" page. It needs no public API access.</li>
+                      <li><code>transitions</code> on an interactive block gives each row the workflow buttons that
+                          apply to it now, and works with <code>scope="mine"</code>. See
+                          <a href="#/docs/usage/actions">Actions</a>.</li>
+                  </ul>
+                  <p>Visitors can right-click any collection display to filter, sort, group, copy, print or export
+                      it. The full attribute list is in <a href="#/docs/usage/shortcodes">Shortcodes</a>; for
+                      joins, totals and per-user results, build a <a href="#/docs/usage/views">View</a>.</p>
+
+                  <h3>Who can see entries</h3>
+                  <ul>
+                      <li>In the admin, the <code>collections</code> permission decides who can view, add, edit and
+                          delete entries.</li>
+                      <li>On pages, a <code>[collection]</code> shows its entries to anyone who can open the page -
+                          gate the page, or use <code>scope="mine"</code> or a View with a row-level rule.</li>
+                      <li>Through the API, the API &amp; Export tab decides: Public, Token (an API token), or signed-in
+                          users with a role and above. A role the site does not have admits only the level-0
+                          role.</li>
+                  </ul>
+
+                  <h3>Forms</h3>
+                  <p>Forms are at <strong>Data &gt; Forms</strong>. A form stores what visitors send in a
+                      collection, and can then email someone, call a webhook, run an Action and show a message or
+                      redirect. Fields can show, hide or require other fields, and triggers can react to answers
+                      (a banner, blocking the submit, jumping a step). Submissions are listed under the form.
+                      Visitors' submissions are kept out of the site's Git repository. See
+                      <a href="#/tutorials/forms">Form Follow-Up</a> and the <a href="#/docs/api/forms">Forms
+                      API</a>.</p>
+
+                  <h3>See also</h3>
+                  <ul>
+                      <li><a href="#/docs/api/collections">Collections API</a>,
+                          <a href="#/docs/api/external">External API &amp; tokens</a> and
+                          <a href="#/docs/api/builder">API Builder</a></li>
+                      <li><a href="#/tutorials/crud">Building a CRUD App</a> - collections, forms, actions and pages
+                          together</li>
+                  </ul>
+
+    </div>
+  </div>
+</div>

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

@@ -10,7 +10,9 @@
 <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>
+                      If the user is not logged in, a warning toast is shown instead. The action decides who may run
+                      it (its roles and row-level rule, checked on the server), and Actions need a MongoDB
+                      connection - see <a href="#/docs/usage/actions">Actions</a>.</p>
 
                   <h3>Syntax &amp; Attributes</h3>
                   <p><strong>Wrapping form:</strong></p>
@@ -116,8 +118,17 @@
                       </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>
+                  <p>CTA buttons appear on the <strong>cards</strong> (card footer), <strong>list</strong> (inline),
+                      <strong>table</strong> (a column of its own) and <strong>block</strong> displays, and on each
+                      row of an interactive Collection Browser. On a <code>scope="mine"</code> block the server
+                      refuses a row the visitor did not create.</p>
+                  <p>A saved View takes the same buttons with <code>action="slug"</code> and the same
+                      <code>cta-label</code>, <code>cta-style</code>, <code>cta-icon</code> and
+                      <code>cta-confirm</code> attributes:</p>
+                  <pre class="code-block"><code>[view slug="pending-applications" display="cards" action="approve-application" cta-label="Approve" /]</code></pre>
+                  <p>For buttons that change with each row's state (Submit, Withdraw, Approve), use
+                      <code>transitions</code> on an interactive <code>[collection]</code> instead - see
+                      <a href="#/docs/usage/actions">Actions</a>.</p>
 
     </div>
   </div>

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

@@ -85,7 +85,6 @@
                   <pre class="code-block"><code>[card id="my-panel" title="Hidden Details"]
 Content goes here.
 [/card]
-
 [dconfig]
 {
   "#my-btn": {
@@ -107,9 +106,7 @@ Content goes here.
   }
 }
 [/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>