Initial commit: Docusaurus docker stack and docs

docs/dotjuice-elementor-tools-pro/espocrm-integration.md

@@ -0,0 +1,54 @@
+# EspoCRM Lead Capture
+
+**Requires Elementor Pro** — this adds a submit action to Elementor Pro's Forms widget, so it only appears if Elementor Pro's Forms module is active.
+
+## Where to find it
+
+Edit any Elementor Form widget, go to **Content → Actions After Submit**, and add **EspoCRM Webhook** to the list of actions. A new "EspoCRM Webhook" settings section appears further down the panel once it's added.
+
+## Setting it up
+
+1. In EspoCRM, create (or open) a **Lead Capture** entry point and copy its webhook URL.
+2. Paste that URL into **Webhook URL** on the form action.
+3. Tell it which fields to send — see **Field mapping** below.
+4. Save and test with a real submission, checking that the lead appears correctly in EspoCRM.
+
+## Settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **Webhook URL** | Empty | Your EspoCRM Lead Capture endpoint. Required — the form shows an error to the visitor if this is empty when they submit. |
+| **EspoCRM Payload Example** | Empty | Paste an example payload copied from EspoCRM's Lead Capture setup here — see below. |
+| **Or Enter Field IDs Manually** | Empty | A comma-separated list of field IDs to send, as an alternative to pasting a payload. |
+| **Format Phone Numbers** | On | Automatically reformats UK phone numbers to `+44 #### ######` before sending. |
+| **Enable Debug Logging** | Off | Logs each submission's request and response to your site's debug log — see the warning below before using this on a live site. |
+
+## Field mapping
+
+This integration works by matching each Elementor form field's **ID** directly against the field name EspoCRM expects — there's no visual field-mapping screen, so the IDs need to line up.
+
+**The easiest way:** copy an example payload from your EspoCRM Lead Capture setup (it looks like `{"firstName": "...", "lastName": "...", "emailAddress": "..."}`) and paste it into **EspoCRM Payload Example**. The field names are extracted automatically — you don't need to type them out separately.
+
+**Alternative:** if you don't have an example payload handy, list the field IDs you want sent, comma-separated, in **Or Enter Field IDs Manually** (e.g. `firstName, lastName, emailAddress`).
+
+**If both are left empty**, every field on the form is sent (except Elementor's own internal fields — acceptance checkboxes, terms, reCAPTCHA, honeypot, which are always excluded automatically).
+
+Either way, each Elementor form field's **ID** must match the corresponding EspoCRM field name exactly. To check or change a field's ID: select the field in the form editor → **Advanced** tab → **ID**.
+
+## Phone number formatting
+
+When **Format Phone Numbers** is on, any field whose ID contains "phone" is reformatted to `+44 #### ######` before sending — handling common UK input styles (a leading `0`, `+44`, or `0044`) automatically. If a number doesn't look like a valid 10-digit UK number after cleanup, it's sent as originally entered rather than a mangled result. This formatting is UK-specific; international numbers are passed through unchanged.
+
+## ⚠ Before enabling debug logging
+
+Debug logging writes each submission's field values — potentially including names, emails, and phone numbers — to your site's debug log file. Only enable this temporarily while troubleshooting a specific issue, and turn it off again afterward. Debug logs aren't intended to store personal data long-term, and depending on your hosting, the log file may be more widely accessible than your database.
+
+## What visitors see if something goes wrong
+
+If the webhook URL is missing, unreachable, or EspoCRM returns an error, the visitor sees a generic error message on the form rather than technical details — enable debug logging temporarily to see exactly what EspoCRM returned.
+
+## Good to know
+
+- **Checkbox/toggle-style fields** are converted to `0`/`1` automatically, matching EspoCRM's expected boolean format.
+- **Multi-select or checkbox-group fields** are sent as a single comma-separated string.
+- **Empty fields are omitted** from the payload entirely rather than sent as blank values.