domma-cms 1.6.60 → 1.7.0

package/docs/guides/mongodb-storage-adapter.md

@@ -0,0 +1,282 @@
+# MongoDB Storage Adapter (Pro Feature)
+
+Domma CMS stores collection entries as JSON files by default. The MongoDB Storage Adapter is an optional Pro feature
+that lets you store collection entries in a MongoDB database instead - with zero changes to the CMS admin interface.
+
+---
+
+## Why Use It
+
+| Reason            | Detail                                                     |
+|-------------------|------------------------------------------------------------|
+| **Scale**         | Handle thousands of entries without directory I/O overhead |
+| **Query power**   | Rich filtering, sorting, and aggregation via MongoDB       |
+| **Mixed mode**    | Some collections on MongoDB, others on file - your choice  |
+| **Seamless swap** | Change one line in `schema.json`; no code changes needed   |
+
+---
+
+## Prerequisites
+
+- MongoDB 6.0 or later (local or hosted - MongoDB Atlas works)
+- Node.js 24+
+- Domma CMS 0.4.0+
+
+---
+
+## Quick Setup
+
+The fastest way to enable Pro mode:
+
+```bash
+npm run pro enable
+```
+
+This will:
+
+1. Copy `config/connections.json.example` → `config/connections.json`
+2. Prompt you for your MongoDB URI and database name
+3. Run `npm install mongodb`
+
+Then restart the server and configure individual collections (see below).
+
+---
+
+## Manual Setup
+
+If you prefer to configure manually:
+
+### 1. Copy the example connections file
+
+```bash
+cp config/connections.json.example config/connections.json
+```
+
+### 2. Edit `config/connections.json`
+
+```json
+{
+    "default": {
+        "type": "mongodb",
+        "uri": "mongodb://localhost:27017",
+        "database": "domma_cms",
+        "options": {}
+    }
+}
+```
+
+| Field      | Description                                    |
+|------------|------------------------------------------------|
+| `type`     | Must be `"mongodb"`                            |
+| `uri`      | MongoDB connection string                      |
+| `database` | Name of the database to use                    |
+| `options`  | Optional extra options passed to `MongoClient` |
+
+> `config/connections.json` is gitignored - credentials stay local and are never committed.
+
+### 3. Install the mongodb package
+
+```bash
+npm install mongodb
+```
+
+### 4. Restart the server
+
+```bash
+npm start
+```
+
+You should see connection log lines like:
+
+```
+[connectionManager] Connected: default → domma_cms
+```
+
+---
+
+## Multiple Connections
+
+You can define any number of named connections:
+
+```json
+{
+    "default": {
+        "type": "mongodb",
+        "uri": "mongodb://localhost:27017",
+        "database": "domma_cms",
+        "options": {}
+    },
+    "atlas": {
+        "type": "mongodb",
+        "uri": "mongodb+srv://user:pass@cluster.mongodb.net",
+        "database": "domma_prod",
+        "options": {}
+    }
+}
+```
+
+Each collection then references a connection by name in its `schema.json`.
+
+---
+
+## Connections in the admin
+
+Admins can edit `config/connections.json` on the **Database connections** tab of **Collections** (`GET`/`PUT /api/collections/connections`)
+instead of by hand; URIs are masked on screen. Connections are opened at startup, so restart after adding or changing
+one.
+
+If a connection fails, collections on it fall back to file storage and the admin raises a critical **Database
+unavailable** notification (source `core:storage`) naming the connection, so the empty lists are explained.
+
+---
+
+## Switching a Collection to MongoDB
+
+Edit the collection's `schema.json` and add a `storage` block:
+
+```json
+{
+    "slug": "products",
+    "title": "Products",
+    "fields": [...],
+    "storage": {
+        "adapter": "mongodb",
+        "connection": "default"
+    }
+}
+```
+
+| Field                | Required | Default     | Description                              |
+|----------------------|----------|-------------|------------------------------------------|
+| `storage.adapter`    | Yes      | `"file"`    | Set to `"mongodb"` to use MongoDB        |
+| `storage.connection` | No       | `"default"` | Named connection from `connections.json` |
+
+The easier way is the collection editor's **Storage** tab (shown once a connection exists): choose the adapter and
+connection and it moves the existing entries across for you (`POST /api/collections/:slug/migrate-storage`), with no
+restart. Moved entries are created afresh in the new store, so they get **new ids and dates** - references to them
+from other collections do not follow. When moving off file storage, the old `data.json` is kept as `data.json.bak`.
+
+If you edit `schema.json` by hand instead, **restart the server**: the adapter registry caches each collection's
+adapter, and only a save through the CMS (or a restart) clears it. A hand edit moves no entries.
+
+---
+
+## Switching Back to File-Based
+
+Remove the `storage` block from `schema.json`:
+
+```json
+{
+    "slug": "products",
+    "title": "Products",
+    "fields": [...]
+}
+```
+
+> **Important:** a hand edit does not move entries back to files. Use the Storage tab, which moves them (with new ids,
+> as above), or export and re-import them.
+
+---
+
+## Mixed Mode
+
+Collections can use different adapters independently:
+
+```
+┌─────────────────────────────────────────────┐
+│              Domma CMS Collections           │
+├──────────────────┬──────────────────────────┤
+│  products        │  → MongoAdapter (default) │
+│  blog-posts      │  → MongoAdapter (atlas)   │
+│  testimonials    │  → FileAdapter            │
+│  roles           │  → FileAdapter (always)   │
+└──────────────────┴──────────────────────────┘
+```
+
+Preset collections - `roles`, `user-profiles`, `projects` and the rest defined in `server/services/presetCollections.js`
+(notes, todo items, contacts and others) - always use the file adapter, whatever their `storage` block says
+(`server/services/adapterRegistry.js`).
+
+---
+
+## How It Works Internally
+
+| Component           | File                                       | Role                                                                     |
+|---------------------|--------------------------------------------|--------------------------------------------------------------------------|
+| Connection Manager  | `server/services/connectionManager.js`     | Creates and caches `MongoClient` instances at startup                    |
+| Adapter Registry    | `server/services/adapterRegistry.js`       | Reads `schema.json` and resolves the correct adapter per collection      |
+| File Adapter        | `server/services/adapters/FileAdapter.js`  | Default; reads/writes JSON files in `content/collections/`               |
+| Mongo Adapter       | `server/services/adapters/MongoAdapter.js` | Reads/writes documents in MongoDB; prefixes collection names with `cms_` |
+| Collections Service | `server/services/collections.js`           | Orchestrates CRUD, delegates I/O to the resolved adapter                 |
+
+### Startup flow
+
+1. Server reads `config/connections.json` (if present)
+2. `connectionManager.initialise()` connects to all named MongoDB servers
+3. Each collection schema is read lazily on first request
+4. `adapterRegistry.getAdapter(slug)` resolves and caches the adapter
+
+### Request flow (entry read/write)
+
+```
+API route → collections.js → adapterRegistry.getAdapter(slug)
+                                     │
+                    ┌────────────────┴─────────────────┐
+                    │                                   │
+               FileAdapter                       MongoAdapter
+            (content/collections/)           (MongoDB via getDb())
+```
+
+---
+
+## Checking Status
+
+```bash
+npm run pro status
+```
+
+Example output (Pro enabled):
+
+```
+  Pro Mode Status
+  ───────────────
+  Mode    : Pro (MongoDB)
+  mongodb : installed ✓
+
+  Connections (1):
+    • default
+      URI      : mongodb://localhost:27017
+      Database : domma_cms
+```
+
+MongoDB URIs with passwords are automatically masked (`****`).
+
+---
+
+## Disabling Pro Mode
+
+```bash
+npm run pro disable
+```
+
+This backs up `config/connections.json` to `config/connections.json.bak` and optionally uninstalls the `mongodb`
+package. The server falls back to file-based storage on next restart.
+
+To re-enable, run `npm run pro enable` or rename the backup:
+
+```bash
+mv config/connections.json.bak config/connections.json
+```
+
+---
+
+## Troubleshooting
+
+| Symptom                                                   | Cause                                                              | Fix                                                             |
+|-----------------------------------------------------------|--------------------------------------------------------------------|-----------------------------------------------------------------|
+| No `[connectionManager] Connected` log line               | `config/connections.json` missing or mongodb not installed         | Run `npm run pro enable`                                        |
+| `Failed to connect "default"` in logs                     | Wrong URI, MongoDB not running, or network issue                   | Check URI in `connections.json` and ensure MongoDB is reachable |
+| `[adapterRegistry] Failed to load MongoAdapter`           | `mongodb` package not installed or connection failed               | Run `npm install mongodb`, check connection logs                |
+| Collection entries appear empty after switching           | `schema.json` was edited by hand, which moves no entries           | Switch with the editor's Storage tab, or export and re-import   |
+| `Unknown connection: "name"` error                        | Connection name in `schema.json` not defined in `connections.json` | Add the named connection to `connections.json` and restart      |
+| A preset collection (`roles`, …) ignores `storage` config | By design - system collections always use file storage             | No fix needed; this is intentional                              |

package/docs/guides/multi-page-forms.md

@@ -0,0 +1,121 @@
+# Multi-Page Forms (Wizards)
+
+Any form in the Form Builder becomes a wizard by adding a **Page Break**. Fields before the
+break are page one, fields after it are page two, and so on. The visitor moves through with
+Previous / Next and submits from the last page.
+
+There is no separate "wizard mode" to switch on - the page breaks are the switch.
+
+---
+
+## Building one
+
+In **Forms → edit a form**, use **Add Page Break** between the fields you want to separate.
+Each break carries two fields of its own:
+
+| Field           | Effect                                                        |
+|-----------------|---------------------------------------------------------------|
+| **Step Title**  | Heading shown above that page                                 |
+| **Description** | Smaller line under the heading; leave blank to omit it        |
+
+The first page has no break before it, so it takes its heading from the form's own title.
+Give it a different one by putting a page break at the very top - a break with nothing before
+it re-titles the page that follows rather than creating an empty page of its own.
+
+A break at the very end is ignored for the same reason: it would produce a final page holding
+nothing but the button.
+
+---
+
+## Layout
+
+Forms are laid out as a **grid** unless you choose otherwise, two columns by
+default and three if you set Columns to 3 - those are the only two the renderer
+produces. A field can be widened with its **Column Span**, or set to **Full
+Width** to take the whole row.
+
+Stacked and Inline are still there under **Settings → Layout** if a form reads
+better one field per line.
+
+**Settings → Submit Button Position** does not move a wizard's buttons: Previous
+and Next / Finish stay at the two ends of the footer on every page, so the button
+never jumps under the visitor's pointer between steps.
+
+The rest of the **Submit Button** card does reach the footer: **Style** and
+**Size** apply to Next and Finish, the icons to Finish only, and Previous takes
+the size. A **second button** (Clear form or a Cancel link) is not shown on a
+multi-step form - Clear on a later page could not clear the pages already
+answered, and the footer already has Previous.
+
+---
+
+## What carries across pages
+
+Everything the single-page form does is applied to each page as the visitor reaches it.
+
+| Feature                | Behaviour across pages                                                |
+|------------------------|-----------------------------------------------------------------------|
+| **Layout / columns**   | The form's Layout and Columns settings apply to every page             |
+| **Field spans**        | A field set to span the full width does so on whichever page it is on  |
+| **Date fields**        | Render as native date pickers on every page                            |
+| **Icon / image fields**| Keep their Browse buttons and previews on every page                   |
+| **Spacers**            | Rendered in place on the page they belong to                           |
+| **File uploads**       | A file chosen on page one is still attached when page three submits    |
+| **Conditional logic**  | A rule on page two can test an answer given on page one                |
+| **Spam protection**    | The honeypot and timing check cover the submission, not just page one  |
+
+Answers are accumulated as the visitor advances, so going **Previous** and changing an answer
+re-evaluates any rule that depends on it.
+
+---
+
+## Validation
+
+Each page validates before it will let the visitor move on - required fields must be filled
+and format rules must pass. The server re-checks everything on submit regardless of what the
+browser allowed, including conditional requirements that depend on answers from other pages.
+
+---
+
+## Preview
+
+The builder's live preview renders the wizard exactly as the public page does: same layout,
+same page splitting, same titles. Stepping through the preview is a fair test of the real
+thing. The preview submits to the real endpoint once the form has been saved, so test
+submissions are stored like any other.
+
+---
+
+## Notes and limits
+
+- **Don't name a field `website`.** It is the name used by the spam honeypot. The CMS steps
+  the honeypot aside if you do, but a clearer field name (`your_website`, `company_url`)
+  avoids the question entirely.
+- **Field names must be unique across the whole form**, not just within a page. Two pages
+  using the same name will overwrite one another.
+- A form made only of page breaks renders as a single empty page.
+
+---
+
+## Where a form is rendered from
+
+Three different pieces of code render a form, depending on how it reaches the
+page. They behave identically, but knowing which one is in play saves time when
+something looks wrong:
+
+| How the form got there                 | Rendered by                     |
+|----------------------------------------|---------------------------------|
+| `[form slug="…" /]` in page content    | `public/js/site.js`             |
+| A hand-written `<div data-form="…">`   | `public/js/forms.js`            |
+| The builder's live preview             | `admin/js/views/form-editor.js` |
+
+All three share `public/js/form-steps.mjs` for splitting a form into pages.
+
+---
+
+## Related
+
+- [Form Triggers](form-triggers.md)
+
+- `docs/configuration.md` - form settings schema
+- Admin → Forms → Settings tab - layout, columns, honeypot, rate limit, and the Submit Button card (text, position, style, size, icons, second button)