domma-cms 0.93.0 → 0.94.0

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

@@ -22,14 +22,14 @@
                       <li><strong>Pipeline tab</strong> - add aggregation stages in order. Each stage has a type and a
                           JSON config object.
                       </li>
-                      <li><strong>Display tab</strong> - choose table or list mode, set page size, and optionally define
-                          column definitions.
+                      <li><strong>Display tab</strong> - choose table, list or block mode, set the page size (1 to 200)
+                          and pick the table's columns.
                       </li>
-                      <li><strong>Access tab</strong> - select which roles can access this view and whether it is
-                          publicly accessible.
+                      <li><strong>Access tab</strong> - choose which roles can read the view's results, whether it is
+                          public, and an optional row-level rule.
                       </li>
-                      <li>Click <strong>Save View</strong>, then use <strong>Preview</strong> to execute and inspect the
-                          results.
+                      <li>Save the view. The <strong>Results</strong> tab runs the pipeline as it stands, saved or
+                          not, and shows the first rows.
                       </li>
                   </ol>
 
@@ -87,20 +87,37 @@
                   <p>Forbidden stages (<code>$out</code>, <code>$merge</code>, <code>$function</code>, <code>$accumulator</code>,
                       <code>$graphLookup</code>) are rejected at save and execution time.</p>
 
-                  <h3>Column Definitions</h3>
-                  <p>On the Display tab, column definitions are a JSON array. Each object has a <code>key</code>
-                      (dot-path into the result document) and a <code>label</code>.</p>
-                  <pre class="code-block"><code>[
-  { "key": "data.name",  "label": "Name" },
-  { "key": "data.email", "label": "Email" },
-  { "key": "orders",     "label": "Orders" }
-]</code></pre>
-                  <p>If no columns are defined, the preview auto-generates columns from the first result document.</p>
+                  <h3>Columns</h3>
+                  <p>On the Display tab, pick which fields the table shows, in order, and what each heading says. The
+                      field lists come from the source collection. With none chosen, the first six fields of the
+                      first result are shown.</p>
 
-                  <h3>Public Access</h3>
-                  <p>Tick <strong>Public</strong> on the Access tab to expose the view via
-                      <code>GET /api/views/:slug/public</code> without requiring a login.
-                      Leave it unticked to require JWT authentication with one of the allowed roles.</p>
+                  <h3>Who can read a view</h3>
+                  <p>The Access tab decides who sees the view's results, both on pages (<code>[view]</code>) and at
+                      <code>GET /api/views/:slug/public</code>:</p>
+                  <ul>
+                      <li><strong>Public</strong> - anyone, signed in or not.</li>
+                      <li><strong>Roles</strong> - signed-in users holding any listed role, and everyone more senior
+                          (the same ladder as page visibility; <code>=role</code> means that role only). A role the
+                          site no longer has admits only the level-0 role.</li>
+                      <li><strong>No roles and not public</strong> - the admin tier only (role levels 0 and 1).</li>
+                  </ul>
+                  <p>A visitor who may not read the view gets its empty message on the page, never the rows.</p>
+
+                  <h3>Row-level rules</h3>
+                  <p>A row-level rule shows each user only the results that are theirs: <strong>Owner</strong>
+                      (entries they created) or <strong>Field match</strong> (entries whose chosen field equals
+                      their id, email, name or role). Totals and page counts count only the rows that user may see,
+                      and the level-0 role sees everything. A page showing such a view is rendered fresh for each
+                      signed-in visitor rather than served from the shared cache.</p>
+
+                  <h3>Showing a view on a page</h3>
+                  <pre class="code-block"><code>[view slug="open-jobs" display="cards" columns="3" title-field="title" /]
+[view slug="open-jobs" searchable sortable page-size="20" /]</code></pre>
+                  <p>The shortcode can use any display (table, cards, list, accordion, timeline, carousel,
+                      listgroup, block); left out, it uses the view's own. Adding <code>searchable</code>,
+                      <code>sortable</code> or <code>paginate</code> makes it interactive. See
+                      <a href="#/docs/usage/shortcodes">Shortcodes</a>.</p>
 
     </div>
   </div>

package/admin/js/templates/documentation.html

@@ -1,5 +1,5 @@
 <div class="view-header">
-  <h1><span data-icon="book"></span> Usage</h1>
+  <h1><span data-icon="book"></span> Documentation</h1>
 </div>
 
 <div class="row">
@@ -7,65 +7,186 @@
     <div class="docs-body">
 
       <p class="lead">
-        Task-by-task reference for running a Domma CMS site. Pick a topic below - each opens as its own
-        page, and every topic is also listed under <strong>Documentation → Usage</strong> in the sidebar.
+        Everything about running and extending a Domma CMS site. Pick a topic below - each opens as its own
+        page, and the same topics are listed under <strong>Documentation</strong> in the sidebar.
       </p>
 
-      <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:1rem;margin-top:1.5rem;">
-
+      <h2 style="margin-top:2rem;">Usage</h2>
+      <p class="text-muted">Task-by-task guides for running the site.</p>
+      <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:1rem;margin-top:1rem;">
         <a href="#/docs/usage/pages" class="card" style="text-decoration:none;display:block;">
           <div class="card-body"><h3 style="margin-top:0;"><span data-icon="file-text"></span> Pages</h3>
-            <p class="text-muted" style="margin-bottom:0;">Markdown pages, YAML frontmatter, and how files map to URLs.</p></div>
+            <p class="text-muted" style="margin-bottom:0;">Markdown pages, frontmatter, drafts, previews, visibility and history.</p></div>
         </a>
         <a href="#/docs/usage/media" class="card" style="text-decoration:none;display:block;">
           <div class="card-body"><h3 style="margin-top:0;"><span data-icon="image"></span> Media</h3>
-            <p class="text-muted" style="margin-bottom:0;">Uploading files and using the media library.</p></div>
+            <p class="text-muted" style="margin-bottom:0;">Uploading files, the image editor and the Media Picker.</p></div>
         </a>
         <a href="#/docs/usage/navigation" class="card" style="text-decoration:none;display:block;">
           <div class="card-body"><h3 style="margin-top:0;"><span data-icon="menu"></span> Navigation</h3>
-            <p class="text-muted" style="margin-bottom:0;">Menus, locations, and the multi-menu system.</p></div>
+            <p class="text-muted" style="margin-bottom:0;">Menus, locations, bindings and who sees each item.</p></div>
         </a>
-        <a href="#/docs/usage/dconfig" class="card" style="text-decoration:none;display:block;">
-          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="settings"></span> DConfig</h3>
-            <p class="text-muted" style="margin-bottom:0;">Declarative, per-page configuration blocks.</p></div>
+        <a href="#/docs/usage/collections" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="database"></span> Collections &amp; Forms</h3>
+            <p class="text-muted" style="margin-bottom:0;">Fields, entries, import and export, storage moves, displays and forms.</p></div>
+        </a>
+        <a href="#/docs/usage/views" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="eye"></span> Views</h3>
+            <p class="text-muted" style="margin-bottom:0;">Saved pipelines over your collections, access and row-level rules.</p></div>
+        </a>
+        <a href="#/docs/usage/actions" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="zap"></span> Actions</h3>
+            <p class="text-muted" style="margin-bottom:0;">Workflow buttons, transitions and who may run them (MongoDB).</p></div>
+        </a>
+        <a href="#/docs/usage/cta-shortcode" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="zap"></span> CTA Shortcode</h3>
+            <p class="text-muted" style="margin-bottom:0;">Action buttons on public pages.</p></div>
         </a>
         <a href="#/docs/usage/shortcodes" class="card" style="text-decoration:none;display:block;">
           <div class="card-body"><h3 style="margin-top:0;"><span data-icon="code"></span> Shortcodes</h3>
-            <p class="text-muted" style="margin-bottom:0;">The full catalogue of in-page shortcodes.</p></div>
+            <p class="text-muted" style="margin-bottom:0;">Every in-page shortcode, including [collection] and effects.</p></div>
+        </a>
+        <a href="#/docs/usage/dconfig" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="settings"></span> DConfig</h3>
+            <p class="text-muted" style="margin-bottom:0;">Declarative click handlers and class toggles per page.</p></div>
         </a>
         <a href="#/docs/usage/site-settings" class="card" style="text-decoration:none;display:block;">
           <div class="card-body"><h3 style="margin-top:0;"><span data-icon="settings"></span> Site Settings</h3>
-            <p class="text-muted" style="margin-bottom:0;">Title, theme, brand, footer and SMTP.</p></div>
+            <p class="text-muted" style="margin-bottom:0;">General, SEO, footer, email, cookies, cache, theme and dates.</p></div>
+        </a>
+        <a href="#/docs/usage/users-roles" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="users"></span> Users &amp; Roles</h3>
+            <p class="text-muted" style="margin-bottom:0;">Accounts, roles, the role ladder, confined roles and resets.</p></div>
+        </a>
+        <a href="#/docs/usage/tools" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="list"></span> Built-in Tools</h3>
+            <p class="text-muted" style="margin-bottom:0;">Contacts, Notes, Todo, Analytics, SEO, notifications and search.</p></div>
         </a>
         <a href="#/docs/usage/plugins" class="card" style="text-decoration:none;display:block;">
           <div class="card-body"><h3 style="margin-top:0;"><span data-icon="package"></span> Plugins</h3>
-            <p class="text-muted" style="margin-bottom:0;">Installing, enabling and configuring plugins.</p></div>
+            <p class="text-muted" style="margin-bottom:0;">The Marketplace: install, update, restarts, switches and dependencies.</p></div>
         </a>
-        <a href="#/docs/usage/users-roles" class="card" style="text-decoration:none;display:block;">
-          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="users"></span> Users &amp; Roles</h3>
-            <p class="text-muted" style="margin-bottom:0;">Accounts, roles and the permission model.</p></div>
+        <a href="#/docs/usage/editions" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="tag"></span> Editions &amp; Licences</h3>
+            <p class="text-muted" style="margin-bottom:0;">Free and Pro, licences, and what happens when one ends.</p></div>
         </a>
-        <a href="#/docs/usage/views" class="card" style="text-decoration:none;display:block;">
-          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="eye"></span> Views</h3>
-            <p class="text-muted" style="margin-bottom:0;">Saved, reusable views over your collections.</p></div>
+        <a href="#/pro/docs" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="layers"></span> Pro Documentation</h3>
+            <p class="text-muted" style="margin-bottom:0;">What needs a MongoDB connection, and what does not.</p></div>
         </a>
-        <a href="#/docs/usage/actions" class="card" style="text-decoration:none;display:block;">
-          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="zap"></span> Actions</h3>
-            <p class="text-muted" style="margin-bottom:0;">Server-side workflow buttons and transitions.</p></div>
+      </div>
+
+      <h2 style="margin-top:2rem;">Plugins</h2>
+      <p class="text-muted">Guides for the Marketplace plugins installed on this site.</p>
+      <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:1rem;margin-top:1rem;">
+        <a href="#/docs/plugins" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="package"></span> Plugin guides</h3>
+            <p class="text-muted" style="margin-bottom:0;">One page per installed plugin you can use: what it does, its screens, settings and permissions.</p></div>
         </a>
-        <a href="#/docs/usage/cta-shortcode" class="card" style="text-decoration:none;display:block;">
-          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="zap"></span> CTA Shortcode</h3>
-            <p class="text-muted" style="margin-bottom:0;">Triggering collection actions from a page.</p></div>
+      </div>
+
+      <h2 style="margin-top:2rem;">Tutorials</h2>
+      <p class="text-muted">End-to-end walkthroughs.</p>
+      <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:1rem;margin-top:1rem;">
+        <a href="#/tutorials/crud" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="database"></span> Building a CRUD App</h3>
+            <p class="text-muted" style="margin-bottom:0;">Collections, forms, actions and pages composed into a working app.</p></div>
+        </a>
+        <a href="#/tutorials/forms" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="layout"></span> Form Follow-Up</h3>
+            <p class="text-muted" style="margin-bottom:0;">Emails, webhooks, Actions and what happens after a submission.</p></div>
         </a>
+        <a href="#/tutorials/plugin" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="package"></span> Writing a Plugin</h3>
+            <p class="text-muted" style="margin-bottom:0;">Server routes, admin screens and page snippets of your own.</p></div>
+        </a>
+      </div>
 
+      <h2 style="margin-top:2rem;">Components</h2>
+      <p class="text-muted">Reusable custom elements (.dmc).</p>
+      <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:1rem;margin-top:1rem;">
+        <a href="#/docs/components" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="book"></span> Reference</h3>
+            <p class="text-muted" style="margin-bottom:0;">The component file format and what it can do.</p></div>
+        </a>
+        <a href="#/docs/components-howto" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="zap"></span> How-To</h3>
+            <p class="text-muted" style="margin-bottom:0;">Short recipes for common components.</p></div>
+        </a>
+        <a href="#/docs/components-walkthrough" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="document"></span> Walkthrough</h3>
+            <p class="text-muted" style="margin-bottom:0;">Building one component from start to finish.</p></div>
+        </a>
+        <a href="#/docs/components-rules" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="shield"></span> Rules</h3>
+            <p class="text-muted" style="margin-bottom:0;">What components may and may not do.</p></div>
+        </a>
       </div>
 
-      <hr style="margin-top:2rem;">
-      <p class="text-muted" style="font-size:.9rem;">
-        New to the CMS? Start with the <a href="#/tutorials">Tutorials</a>. Building reusable elements?
-        See <a href="#/docs/components">Components</a>. Integrating externally? See the
-        <a href="#/api-reference">API Reference</a>.
-      </p>
+      <h2 style="margin-top:2rem;">API Reference</h2>
+      <p class="text-muted">The REST API, for integrations and headless use.</p>
+      <div style="display:grid;grid-template-columns:repeat(auto-fill,minmax(240px,1fr));gap:1rem;margin-top:1rem;">
+        <a href="#/docs/api/authentication" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="shield"></span> Authentication</h3>
+            <p class="text-muted" style="margin-bottom:0;">Sign-in, tokens, sessions and password resets.</p></div>
+        </a>
+        <a href="#/docs/api/external" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="lock"></span> External API &amp; tokens</h3>
+            <p class="text-muted" style="margin-bottom:0;">/api/v1 collection access with project API tokens.</p></div>
+        </a>
+        <a href="#/docs/api/builder" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="code"></span> API Builder</h3>
+            <p class="text-muted" style="margin-bottom:0;">Named read-only endpoints over collection data at /api/x.</p></div>
+        </a>
+        <a href="#/docs/api/pages" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="file-text"></span> Pages</h3>
+            <p class="text-muted" style="margin-bottom:0;">Pages, previews, share links and versions.</p></div>
+        </a>
+        <a href="#/docs/api/collections" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="database"></span> Collections</h3>
+            <p class="text-muted" style="margin-bottom:0;">Schemas, entries, import, export and storage moves.</p></div>
+        </a>
+        <a href="#/docs/api/forms" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="layout"></span> Forms</h3>
+            <p class="text-muted" style="margin-bottom:0;">Forms and their submissions.</p></div>
+        </a>
+        <a href="#/docs/api/views" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="eye"></span> Views</h3>
+            <p class="text-muted" style="margin-bottom:0;">Running saved views.</p></div>
+        </a>
+        <a href="#/docs/api/actions" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="zap"></span> Actions</h3>
+            <p class="text-muted" style="margin-bottom:0;">Running actions and transitions.</p></div>
+        </a>
+        <a href="#/docs/api/scaffold" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="layers"></span> Scaffold</h3>
+            <p class="text-muted" style="margin-bottom:0;">Building a working system - collection, form, Actions and more - from a recipe.</p></div>
+        </a>
+        <a href="#/docs/api/media" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="image"></span> Media</h3>
+            <p class="text-muted" style="margin-bottom:0;">Uploads and image transforms.</p></div>
+        </a>
+        <a href="#/docs/api/navigation" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="menu"></span> Menus</h3>
+            <p class="text-muted" style="margin-bottom:0;">Menus, locations and context menus.</p></div>
+        </a>
+        <a href="#/docs/api/users" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="users"></span> Users</h3>
+            <p class="text-muted" style="margin-bottom:0;">Accounts, roles and admin resets.</p></div>
+        </a>
+        <a href="#/docs/api/settings" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="settings"></span> Settings</h3>
+            <p class="text-muted" style="margin-bottom:0;">Site settings and theme.</p></div>
+        </a>
+        <a href="#/docs/api/layouts" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="layout"></span> Layouts</h3>
+            <p class="text-muted" style="margin-bottom:0;">Page layout presets.</p></div>
+        </a>
+        <a href="#/docs/api/plugins" class="card" style="text-decoration:none;display:block;">
+          <div class="card-body"><h3 style="margin-top:0;"><span data-icon="package"></span> Plugins</h3>
+            <p class="text-muted" style="margin-bottom:0;">The Marketplace, installs and Tool switches.</p></div>
+        </a>
+      </div>
 
     </div>
   </div>

package/admin/js/templates/plugin-guide.html

@@ -0,0 +1,15 @@
+<div class="view-header">
+  <h1><span id="pg-icon"><span data-icon="package"></span></span> <span id="pg-title">Plugin guide</span></h1>
+  <div class="pg-actions">
+    <a id="pg-tool" class="btn btn-outline btn-sm" hidden><span data-icon="external-link"></span> <span id="pg-tool-text">Open</span></a>
+    <a href="#/docs/plugins" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> All plugin guides</a>
+  </div>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <p id="pg-meta" class="text-muted pg-meta"></p>
+    <nav id="pg-pages" class="pg-pages" aria-label="Guide pages" hidden></nav>
+    <div id="pg-body" class="docs-body pg-body"></div>
+  </div>
+</div>

package/admin/js/templates/plugin-guides.html

@@ -0,0 +1,21 @@
+<div class="view-header">
+  <h1><span data-icon="package"></span> Plugin Guides</h1>
+  <a href="#/documentation" class="btn btn-ghost btn-sm"><span data-icon="arrow-left"></span> Documentation</a>
+</div>
+
+<div class="row">
+  <div class="col-12">
+    <div class="docs-body">
+      <p class="lead">
+        How to use each plugin installed on this site. A guide appears here when its plugin is enabled, and only
+        to people whose role can use that plugin. Every guide is also listed under
+        <strong>Documentation &gt; Plugins</strong> in the sidebar.
+      </p>
+      <p id="pg-empty" class="text-muted" hidden>
+        No plugin guides for you yet. Guides come with the plugins in the <a href="#/plugins">Marketplace</a>;
+        an enabled plugin you cannot use is not listed.
+      </p>
+      <div id="pg-grid" class="pg-grid"></div>
+    </div>
+  </div>
+</div>