domma-cms 0.25.14 → 0.25.16

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

@@ -0,0 +1,344 @@
+<div class="view-header">
+  <h1><span data-icon="document"></span> Building a CRUD App</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" id="tutorial-crud">
+
+      <p class="lead">
+        A "CRUD app" — Create, Read, Update, Delete — is the shape of almost every business
+        tool you'll ever build. Onboarding, bookings, contacts, tickets, orders, RSVPs,
+        classified ads. Domma CMS gives you everything to build one without writing
+        JavaScript, but the trick is understanding <em>why</em> the pieces compose the way
+        they do. That's what this tutorial is for.
+      </p>
+
+      <hr>
+
+      <h2>The mental model</h2>
+
+      <p>Before we build anything, the picture you want in your head:</p>
+
+      <p>A CRUD app is just <strong>somewhere to put data</strong>, <strong>a way for people to give it to you</strong>,
+        <strong>buttons that change it once it's there</strong>, and <strong>a page that shows it back</strong>.
+        Domma CMS gives each of those a name:</p>
+
+      <ul>
+        <li><strong>Collection</strong> — the data store. Think "spreadsheet": rows are records, columns are fields with types.</li>
+        <li><strong>Form</strong> — how new records get added. It writes to a Collection on submit.</li>
+        <li><strong>Action</strong> — a server-side button that changes existing records. "Approve", "Withdraw", "Send invoice".</li>
+        <li><strong>Page</strong> — a Markdown page with <em>shortcodes</em> that render forms and lists from your collections.</li>
+      </ul>
+
+      <p>These are deliberately separate. A single Collection might be written to by three different Forms
+        (one for staff, one for the public, one for an import job) and read by four different Pages (a
+        dashboard, a public listing, a per-user "my entries" view, a printable report). Keeping them
+        separate is what lets the same data drive multiple experiences.</p>
+
+      <div class="alert alert-info">
+        <strong>Why not a database?</strong> Collections store as flat JSON files on disk by default —
+        no database to install, no SQL to learn, no migrations. When you outgrow that, switch
+        individual collections to MongoDB without changing any of your pages or forms. The
+        compatibility layer is the point.
+      </div>
+
+      <hr>
+
+      <h2>Step 1 — Create the Collection (your data store)</h2>
+
+      <p>Open <a href="#/collections">Collections</a> → <strong>New collection</strong>. You'll give it a
+        slug (the URL-safe name we use in shortcodes), a title, and a list of fields.</p>
+
+      <p><strong>The slug matters more than you'd think.</strong> It's what every Form, Action, and shortcode
+        uses to refer to this collection — so pick a noun and stick with it. <code>jobs</code>,
+        <code>applications</code>, <code>contacts</code>, <code>events</code>. Don't pluralise inconsistently
+        and don't include the word "data" or "collection" in the slug — that's redundant.</p>
+
+      <p><strong>Fields are where the design lives.</strong> Each field has a <em>type</em>, and the type isn't
+        just for show — it drives every downstream behaviour:</p>
+
+      <ul>
+        <li><code>text</code> renders a text input on forms and is searchable in the Browser</li>
+        <li><code>number</code> renders a number input, gets a min/max range filter automatically</li>
+        <li><code>select</code> with options becomes a dropdown both on forms AND in the filter rail</li>
+        <li><code>multiselect</code> becomes a checkbox group AND a filterable tag chip set</li>
+        <li><code>date</code> renders a date picker AND gets a from/to range filter</li>
+        <li><code>file</code> renders a file upload with mime/size validation</li>
+        <li><code>reference</code> stores a link to another collection's entry — auto-renders as a populated dropdown</li>
+      </ul>
+
+      <p>Pick the right type at design time and you get the right form input, the right filter UI, and the
+        right validation, all for free. Pick <code>text</code> for everything and you have to recreate all
+        that yourself.</p>
+
+      <p><strong>Tip:</strong> always include a <code>status</code> field as a <code>select</code> with values
+        like <em>pending</em>, <em>reviewing</em>, <em>approved</em>, <em>rejected</em>. This is what makes
+        state-machine transitions possible later. You don't need it until you do, but adding it later means
+        back-filling every existing record. Add it on day one.</p>
+
+      <hr>
+
+      <h2>Step 2 — Read the data (display it on a page)</h2>
+
+      <p>You don't need code to list a Collection on a public page. Drop this in any Markdown page:</p>
+
+      <pre class="code-block"><code>[collection slug="jobs" display="cards" columns="3"
+  title-field="title" sort="postedAt" order="desc"
+  fields="company,location,salary,type" /]</code></pre>
+
+      <p>That single shortcode gives you a server-rendered, cached, SEO-friendly grid of cards. The server
+        reads the collection at request time, filters it, sorts it, and produces static HTML — every
+        visitor gets the same instant render. The page is cached per role, so a million visitors viewing
+        a public page hit the cache and never touch the data store.</p>
+
+      <p><strong>Five display modes are built in:</strong></p>
+
+      <ul>
+        <li><code>display="table"</code> — sortable, paginated, with a search box</li>
+        <li><code>display="cards"</code> — visual grid (default 3 columns; configurable)</li>
+        <li><code>display="list"</code> — vertical stack with title + meta</li>
+        <li><code>display="accordion"</code> — expandable rows, title visible, body hidden until clicked</li>
+        <li><code>display="timeline"</code> — chronological with dates and statuses</li>
+      </ul>
+
+      <p>All five display the same data; you pick the right shape for the page. A directory might use
+        <code>cards</code>; an admin overview might use <code>table</code>; a history page might use
+        <code>timeline</code>.</p>
+
+      <h3>Make it interactive — flip on the Browser</h3>
+
+      <p>Adding any of <code>searchable</code>, <code>filterable</code>, or <code>sortable</code> upgrades the
+        static list to a full <strong>Collection Browser</strong>:</p>
+
+      <pre class="code-block"><code>[collection slug="jobs" display="cards" columns="3"
+  searchable
+  filterable="location,type,salary,tags"
+  sortable
+  page-size="9"
+  empty="No matching jobs." /]</code></pre>
+
+      <p>Now the page has a search box, a filter rail down the left side, a sort dropdown, and pagination —
+        all generated automatically from the schema you wrote in Step 1. The Browser is the moment your
+        app starts to feel like an app rather than a brochure.</p>
+
+      <p><strong>Why the filter rail is automatic:</strong> remember each field has a type? The Browser
+        reads those types and builds the appropriate control. <code>location</code> (text) becomes a
+        dropdown of distinct values harvested from the data. <code>salary</code> (number) becomes a
+        min/max range with a slider. <code>tags</code> (multiselect) becomes toggleable chips with counts.
+        You authored zero filter logic.</p>
+
+      <hr>
+
+      <h2>Step 3 — Create new records (the Form)</h2>
+
+      <p>Open <a href="#/forms">Forms</a> → <strong>New form</strong>. The slug here is the form's identity —
+        what you embed on a page with <code>[form name="..." /]</code>.</p>
+
+      <p>Form fields can mirror the collection fields exactly, or they can be a subset. <strong>You almost
+        always want a subset.</strong> Fields like <code>status</code> shouldn't appear on a public-facing
+        submission form — the form should set status to <em>"pending"</em> automatically. Fields like
+        <code>internalNotes</code> shouldn't be visible to the submitter at all. The form is your
+        audience-facing slice of the collection; design it for who's filling it in.</p>
+
+      <p>Wire the form to the collection in <strong>Actions → Collection</strong>: enable it and pick the
+        target collection slug. Every submission becomes one new entry in that collection. Done.</p>
+
+      <h3>Identity capture (the small thing that makes everything work)</h3>
+
+      <p>When a signed-in user submits a form, the CMS automatically stamps the new entry with their user
+        id (in the entry's <code>meta.createdBy</code>) AND passes their identity into any actions the
+        form fires. That's how the "My applications" view later works without any extra config: you ask
+        for "entries created by the current user" and the platform already has that data.</p>
+
+      <p>Anonymous submissions still work — <code>createdBy</code> is null and the action receives an empty
+        user. So one form can serve both anonymous contact-us submissions AND authenticated apply-for-this-job
+        submissions; the difference shows up in what the action templates can resolve.</p>
+
+      <hr>
+
+      <h2>Step 4 — Change records over time (the Action)</h2>
+
+      <p>This is where most no-code platforms top out. An Action is a server-side button: visitors click it
+        on a page, the server runs a sequence of steps against the entry they clicked on, and the page
+        refreshes.</p>
+
+      <p>Steps include: <code>updateField</code> (set one field to a new value), <code>deleteEntry</code>
+        (remove the entry), <code>createInCollection</code> (write a related entry to another collection
+        — this is how "apply for this job" creates an application without losing the job), <code>email</code>
+        (send a notification using the entry's fields as template variables), and <code>webhook</code>
+        (POST to an external service).</p>
+
+      <h3>The transition is the magic word</h3>
+
+      <p>Actions can declare a <strong>transition</strong> — "this action moves the entry's status from
+        <em>pending</em> to <em>reviewing</em>". That single addition unlocks two huge things:</p>
+
+      <ol>
+        <li><strong>Server-side guard.</strong> Try to run "withdraw" on an already-rejected application
+          and the server refuses with HTTP 409. The illegal move can't happen, even if someone copies
+          and edits the URL.
+        </li>
+        <li><strong>Per-row UI.</strong> Add <code>transitions</code> to a <code>[collection]</code> block
+          and each row sprouts buttons for exactly the transitions legally available given that row's
+          current status AND the viewer's role. A candidate sees "Withdraw" on their pending application;
+          an admin sees "Move to reviewing"; a candidate viewing a rejected application sees nothing
+          to click. No client-side conditionals; the rules live entirely in the action definitions.
+        </li>
+      </ol>
+
+      <pre class="code-block"><code>{
+  "slug": "withdraw-application",
+  "title": "Withdraw",
+  "collection": "applications",
+  "transition": { "field": "status", "from": ["submitted", "reviewing"], "to": "withdrawn" },
+  "access": { "roles": ["candidate"], "rowLevel": { "mode": "owner" } },
+  "steps": [
+    { "type": "updateField", "config": { "field": "status", "value": "withdrawn" } }
+  ]
+}</code></pre>
+
+      <p>Read that JSON like a sentence: <em>"Anyone with the candidate role can withdraw their own
+        application as long as it's currently submitted or reviewing."</em> The platform enforces every
+        clause: <code>access.roles</code> for the role check, <code>rowLevel.mode: 'owner'</code> so
+        candidates can only touch their own entries, <code>transition.from</code> for the status guard.
+        Together they're the whole authorisation policy for this one button.</p>
+
+      <hr>
+
+      <h2>Step 5 — Who sees what (Visibility + scope)</h2>
+
+      <p>Pages have a <code>visibility</code> frontmatter field that decides who can load the page at all.
+        It accepts a single role (<em>"editor and everyone above"</em>) or an array of roles
+        (<em>"candidates OR employers"</em>). Roles are hierarchical — higher-privilege roles inherit
+        access to lower-privilege gated pages without you adding them explicitly.</p>
+
+      <p>For per-user data <em>within</em> a page that mixed-role users share — like a "My applications"
+        block on a dashboard that both candidates and employers visit — use <code>scope="mine"</code>:</p>
+
+      <pre class="code-block"><code>[collection slug="applications" scope="mine"
+  display="cards" title-field="jobId"
+  fields="jobId,status,submittedAt"
+  empty="You haven't applied yet." /]</code></pre>
+
+      <p>The page itself stays cached per role; the per-user block renders client-side via a small hydration
+        request that injects <code>createdBy = current-user-id</code> server-side (the client can never
+        tamper with which user's data they see). Anonymous visitors see a sign-in prompt where the block
+        would render.</p>
+
+      <p>For cross-collection scoping — <em>"recruiter sees only applications for jobs they posted"</em> —
+        use the <code>reference</code> row-access mode in your action's <code>access.rowLevel</code>. The
+        platform resolves the reference to check ownership on the target. <a
+            href="/docs/configuration.md" target="_blank">Full row-access reference</a> covers all three
+        modes (<code>owner</code>, <code>field</code>, <code>reference</code>) with worked examples.</p>
+
+      <hr>
+
+      <h2>Step 6 — Files, references, and "feels like a real app"</h2>
+
+      <p>Three field types deserve their own mention because they're where Domma stops looking like a CMS
+        and starts looking like a development platform:</p>
+
+      <p><strong>File fields</strong> (<code>type: "file"</code>) render a native file picker that uploads
+        to <code>/content/media/</code> with mime + size validation, then stores a reference object
+        <code>{url, name, size, mime}</code> on the entry. Image mimes auto-display as thumbnails on the
+        page; PDFs and docs become "download" links. The form switches to multipart submission
+        automatically the moment any file input has a selection — no extra config.</p>
+
+      <p><strong>Reference fields</strong> (<code>type: "reference"</code>) store the id of another
+        collection's entry. The form picker becomes a populated dropdown of the target collection's
+        entries (showing the <code>displayField</code>); the page display resolves to the readable label
+        everywhere; with a <code>linkTemplate</code> the label becomes a clickable link to the target's
+        detail page. Validation refuses to save an entry pointing at a non-existent target. Dangling
+        references (target deleted later) render as "<em>id</em> (missing)" instead of crashing the page.</p>
+
+      <p><strong>Status fields</strong> with <code>options</code> + paired <code>transition</code>-bearing
+        actions = a workflow. We covered this in Step 4 but it deserves repeating: the combination of a
+        typed status field, a few actions with <code>transition.from</code>, and the <code>transitions</code>
+        attribute on a <code>[collection]</code> shortcode gives you a real state machine that's enforced
+        everywhere (UI, API, audit) with no JavaScript.</p>
+
+      <hr>
+
+      <h2>Step 7 — The Browser tour (advanced reading UI)</h2>
+
+      <p>We touched on the Browser in Step 2. Here's the rest of what it does for free once you turn it
+        on with <code>searchable filterable=... sortable</code>:</p>
+
+      <ul>
+        <li><strong>Faceted filter counts</strong> — every filter chip shows the count of entries that
+          would match if that option were toggled with current other filters. Standard ecommerce-style
+          faceted browsing.</li>
+        <li><strong>Empty state with "Clear filters"</strong> — when the user narrows to zero results,
+          one click resets and gets them un-stuck.</li>
+        <li><strong>Saved searches</strong> — dropdown in the header lets users name and recall their
+          favourite filter combinations.</li>
+        <li><strong>CSV export</strong> — add <code>exportable</code> and a button generates a CSV of the
+          current filtered set.</li>
+        <li><strong>Mobile filter drawer</strong> — narrow viewports get a "Filters (n)" button that
+          slides the rail in from the left as an overlay.</li>
+        <li><strong>URL state sync</strong> — every change writes to the URL query string, so deep-links
+          and the browser back button work.</li>
+        <li><strong>Relevance sort during search</strong> — when the search box has a term, results
+          re-order by match count with a 3× boost on matches in the title field.</li>
+        <li><strong>Keyboard shortcuts</strong> — <code>/</code> focuses search, <code>←</code>/<code>→</code>
+          pages.</li>
+        <li><strong>Infinite scroll</strong> — <code>pagination="scroll"</code> replaces the pager with
+          a sentinel that loads more on scroll.</li>
+        <li><strong>Server-mode for huge datasets</strong> — <code>mode="server"</code> makes every
+          change round-trip to the API; the storage adapter (Mongo or File) handles the query;
+          authoring stays identical.</li>
+      </ul>
+
+      <p>None of this requires any JavaScript on your part. You add attribute names to a shortcode.</p>
+
+      <hr>
+
+      <h2>Pulling it together — the worked example</h2>
+
+      <p>A <strong>job board</strong> uses every primitive in this tutorial:</p>
+
+      <ol>
+        <li>Two collections: <code>jobs</code> (employer posts roles) and <code>applications</code> (candidates apply)</li>
+        <li><code>applications</code> has a <code>reference</code> field <code>jobId</code> pointing at <code>jobs</code></li>
+        <li><code>applications</code> has a <code>file</code> field <code>resume</code> for the candidate's PDF</li>
+        <li>A public <code>[collection slug="jobs"]</code> on <code>/jobs</code> with the Browser turned on</li>
+        <li>An apply form that writes to <code>applications</code> + an action that emails HR</li>
+        <li>A dashboard at <code>/dashboard</code> with <code>visibility: [candidate, employer]</code> and
+          two <code>[collection scope="mine"]</code> blocks (one per role)</li>
+        <li>Transition actions: <em>start-review</em>, <em>invite-to-interview</em>, <em>make-offer</em>,
+          <em>reject</em>, <em>withdraw</em> — each with its own role + state guards</li>
+        <li>The candidate dashboard adds <code>transitions</code> and each row gets the right buttons
+          for its current status</li>
+        <li>Recruiters get <code>access.rowLevel: { mode: 'reference', field: 'jobId', targetCollection: 'jobs' }</code>
+          on their transition actions so they only ever see applications for jobs they posted</li>
+      </ol>
+
+      <p>That's a complete recruitment platform built in pure JSON + Markdown. The full annotated build
+        lives at <a href="/docs/recruitment-recipe.md" target="_blank">docs/recruitment-recipe.md</a>.</p>
+
+      <hr>
+
+      <h2>Skip ahead — scaffold a working CRUD system in one click</h2>
+
+      <p>Reading is one thing; having a real working subsystem to poke at is another. The CMS ships with
+        starter <em>recipes</em> that scaffold a complete Collection + Form + Actions in a single
+        operation. Try one now:</p>
+
+      <div id="tutorial-scaffolder-mount" style="margin-top:1rem;"></div>
+
+      <p class="text-muted" style="margin-top:1rem;font-size:.9rem;">
+        Recipes are JSON files under <code>server/services/recipes/</code> — copy one as a starting
+        point for your own. The <a href="/docs/scaffolding.md" target="_blank">scaffolding docs</a>
+        cover the recipe format in full.
+      </p>
+
+      <hr>
+      <p class="text-muted" style="font-size:.9rem;">
+        Next: <a href="#/tutorials/plugin">Writing a Plugin →</a>
+      </p>
+
+    </div>
+  </div>
+</div>

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

@@ -0,0 +1,93 @@
+<div class="view-header">
+  <h1><span data-icon="document"></span> Form Follow-Up</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>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>
+
+      <hr>
+      <p class="text-muted" style="font-size:.9rem;">
+        <a href="#/tutorials">← Back to all tutorials</a>
+      </p>
+
+    </div>
+  </div>
+</div>