From d5b8c97ec3d74cd51aafbf7aeb2910e444ecba4d Mon Sep 17 00:00:00 2001 From: Johan Date: Wed, 15 Jul 2026 18:57:47 +0000 Subject: [PATCH] Initial commit: Docusaurus docker stack and docs --- .env | 12 ++ README.md | 73 +++++++++++ docker-compose.yaml | 30 +++++ .../_category_.json | 5 + .../espocrm-integration.md | 54 ++++++++ .../getting-started.md | 46 +++++++ .../license-activation.md | 43 +++++++ .../widgets/_category_.json | 4 + .../widgets/acf-frontend-form.md | 32 +++++ .../widgets/woo-add-product-tab.md | 27 ++++ .../widgets/woo-cart.md | 44 +++++++ .../widgets/woo-custom-product-tabs.md | 46 +++++++ .../widgets/woo-product-filter.md | 55 +++++++++ .../widgets/woo-quick-view-popup.md | 34 ++++++ .../widgets/woo-quick-view.md | 40 ++++++ docs/dotjuice-elementor-tools/_category_.json | 5 + .../getting-started.md | 42 +++++++ .../product-attribute-colours.md | 26 ++++ .../screenshot-api-settings.md | 29 +++++ .../widgets/_category_.json | 4 + .../widgets/dark-mode-toggle.md | 34 ++++++ .../widgets/extended-product-loop.md | 31 +++++ .../widgets/keyword-linker.md | 33 +++++ .../widgets/markdown-widget.md | 27 ++++ .../widgets/screenshot-capture.md | 40 ++++++ .../widgets/woo-add-to-cart-transform.md | 31 +++++ .../widgets/woo-categories-transform.md | 36 ++++++ .../widgets/woo-my-account-transform.md | 23 ++++ .../widgets/woo-page-numbers.md | 29 +++++ .../widgets/woo-taxonomy-list.md | 61 ++++++++++ .../woocommerce-account-settings.md | 32 +++++ docs/dotjuice-pagespeed/_category_.json | 5 + docs/dotjuice-pagespeed/advanced.md | 30 +++++ docs/dotjuice-pagespeed/caching.md | 45 +++++++ docs/dotjuice-pagespeed/cdn.md | 34 ++++++ docs/dotjuice-pagespeed/css-optimisation.md | 34 ++++++ docs/dotjuice-pagespeed/database.md | 34 ++++++ docs/dotjuice-pagespeed/getting-started.md | 40 ++++++ docs/dotjuice-pagespeed/html-optimisation.md | 26 ++++ docs/dotjuice-pagespeed/images.md | 24 ++++ .../javascript-optimisation.md | 40 ++++++ docs/dotjuice-pagespeed/preload.md | 34 ++++++ docs/dotjuice-pagespeed/troubleshooting.md | 39 ++++++ docs/intro.md | 16 +++ site/.dockerignore | 4 + site/.gitignore | 20 +++ site/Dockerfile | 15 +++ site/README.md | 43 +++++++ site/docs/.gitkeep | 1 + site/docusaurus.config.js | 115 ++++++++++++++++++ site/package.json | 45 +++++++ site/sidebars.js | 15 +++ site/src/components/HomepageFeatures/index.js | 49 ++++++++ .../HomepageFeatures/styles.module.css | 11 ++ site/src/css/custom.css | 39 ++++++ site/src/pages/index.js | 41 +++++++ site/src/pages/index.module.css | 23 ++++ site/src/pages/markdown-page.mdx | 7 ++ site/static/.nojekyll | 0 site/static/img/dotjuice-logo.png | Bin 0 -> 11166 bytes site/static/img/favicon.ico | Bin 0 -> 3626 bytes 61 files changed, 1857 insertions(+) create mode 100644 .env create mode 100644 README.md create mode 100644 docker-compose.yaml create mode 100644 docs/dotjuice-elementor-tools-pro/_category_.json create mode 100755 docs/dotjuice-elementor-tools-pro/espocrm-integration.md create mode 100755 docs/dotjuice-elementor-tools-pro/getting-started.md create mode 100755 docs/dotjuice-elementor-tools-pro/license-activation.md create mode 100644 docs/dotjuice-elementor-tools-pro/widgets/_category_.json create mode 100755 docs/dotjuice-elementor-tools-pro/widgets/acf-frontend-form.md create mode 100755 docs/dotjuice-elementor-tools-pro/widgets/woo-add-product-tab.md create mode 100755 docs/dotjuice-elementor-tools-pro/widgets/woo-cart.md create mode 100755 docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md create mode 100755 docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md create mode 100755 docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view-popup.md create mode 100755 docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view.md create mode 100644 docs/dotjuice-elementor-tools/_category_.json create mode 100755 docs/dotjuice-elementor-tools/getting-started.md create mode 100755 docs/dotjuice-elementor-tools/product-attribute-colours.md create mode 100755 docs/dotjuice-elementor-tools/screenshot-api-settings.md create mode 100644 docs/dotjuice-elementor-tools/widgets/_category_.json create mode 100755 docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md create mode 100755 docs/dotjuice-elementor-tools/widgets/extended-product-loop.md create mode 100755 docs/dotjuice-elementor-tools/widgets/keyword-linker.md create mode 100755 docs/dotjuice-elementor-tools/widgets/markdown-widget.md create mode 100755 docs/dotjuice-elementor-tools/widgets/screenshot-capture.md create mode 100755 docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md create mode 100755 docs/dotjuice-elementor-tools/widgets/woo-categories-transform.md create mode 100755 docs/dotjuice-elementor-tools/widgets/woo-my-account-transform.md create mode 100755 docs/dotjuice-elementor-tools/widgets/woo-page-numbers.md create mode 100755 docs/dotjuice-elementor-tools/widgets/woo-taxonomy-list.md create mode 100755 docs/dotjuice-elementor-tools/woocommerce-account-settings.md create mode 100644 docs/dotjuice-pagespeed/_category_.json create mode 100755 docs/dotjuice-pagespeed/advanced.md create mode 100755 docs/dotjuice-pagespeed/caching.md create mode 100755 docs/dotjuice-pagespeed/cdn.md create mode 100755 docs/dotjuice-pagespeed/css-optimisation.md create mode 100755 docs/dotjuice-pagespeed/database.md create mode 100755 docs/dotjuice-pagespeed/getting-started.md create mode 100755 docs/dotjuice-pagespeed/html-optimisation.md create mode 100755 docs/dotjuice-pagespeed/images.md create mode 100755 docs/dotjuice-pagespeed/javascript-optimisation.md create mode 100755 docs/dotjuice-pagespeed/preload.md create mode 100755 docs/dotjuice-pagespeed/troubleshooting.md create mode 100644 docs/intro.md create mode 100644 site/.dockerignore create mode 100644 site/.gitignore create mode 100644 site/Dockerfile create mode 100644 site/README.md create mode 100644 site/docs/.gitkeep create mode 100644 site/docusaurus.config.js create mode 100644 site/package.json create mode 100644 site/sidebars.js create mode 100644 site/src/components/HomepageFeatures/index.js create mode 100644 site/src/components/HomepageFeatures/styles.module.css create mode 100644 site/src/css/custom.css create mode 100644 site/src/pages/index.js create mode 100644 site/src/pages/index.module.css create mode 100644 site/src/pages/markdown-page.mdx create mode 100644 site/static/.nojekyll create mode 100755 site/static/img/dotjuice-logo.png create mode 100644 site/static/img/favicon.ico diff --git a/.env b/.env new file mode 100644 index 0000000..8afccb9 --- /dev/null +++ b/.env @@ -0,0 +1,12 @@ +# Container name — this is the DNS name Nginx Proxy Manager forwards to on +# the "proxy" network (Forward Hostname/IP: docusaurus-docs, Port: 3000). +CONTAINER_NAME=docusaurus-docs + +# Port Docusaurus serves on inside the container. +PORT=3000 + +# Production URL of the docs site. Update this once you've picked the +# subdomain, then run `docker compose up -d --build` to rebuild with it — +# Docusaurus bakes the URL into the built site (canonical links, sitemap, +# social card meta tags), it isn't read at request time. +SITE_URL=https://docs.dotjuice.co.uk diff --git a/README.md b/README.md new file mode 100644 index 0000000..48471c4 --- /dev/null +++ b/README.md @@ -0,0 +1,73 @@ +# Dotjuice Docs (Docusaurus) + +Self-hosted documentation site, built with [Docusaurus](https://docusaurus.io) v3.10.2. + +## Layout + +``` +docker-compose.yaml # the stack +.env # container name, port, production URL +site/ # the Docusaurus app itself (config, theme, homepage) — built into the image +docs/ # the actual markdown content — bind-mounted, edit freely without rebuilding +``` + +`docs/` is organised one folder per plugin, matching the sidebar: + +``` +docs/ + intro.md # docs landing page (served at /docs/) + dotjuice-elementor-tools/ # free plugin + getting-started.md + screenshot-api-settings.md + woocommerce-account-settings.md + product-attribute-colours.md + widgets/ # one file per widget + dotjuice-elementor-tools-pro/ # pro plugin + getting-started.md + license-activation.md + widgets/ + dotjuice-pagespeed/ # pagespeed plugin (flat, no widgets/ subfolder) + getting-started.md + caching.md, css-optimisation.md, ... +``` + +Each plugin folder has a `_category_.json` controlling its sidebar label and position — the sidebar itself is fully auto-generated from this folder structure (`sidebars.js`), so adding a new `.md` file anywhere under `docs/` makes it appear automatically, no config edit needed. + +## Spinning it up + +```bash +cd /home/jandieman/docker/docusaurus +docker compose up -d --build +``` + +First build takes a minute or two (`npm install` inside the image). After that, `docker compose logs -f docusaurus` should show `[SUCCESS] Serving "build" directory at: http://0.0.0.0:3000/`. + +Point Nginx Proxy Manager's proxy host at: +- **Forward Hostname/IP:** `docusaurus-docs` (the container name — resolvable by any container on the shared `proxy` network) +- **Forward Port:** `3000` + +## Editing content + +Edit or add markdown files under `docs/`, then either: + +```bash +docker compose restart docusaurus # picks up doc changes, same image +``` + +or, if you've changed `site/` (theme, config, navbar, homepage): + +```bash +docker compose up -d --build # rebuilds the image too +``` + +Either way, the container rebuilds the static site fresh on every start — there's no separate "build step" to remember, just restart the container after editing. + +## Changing the production URL + +Edit `SITE_URL` in `.env`, then `docker compose up -d --build`. Docusaurus bakes this URL into the built site (canonical links, sitemap, social-card meta tags), so it needs a rebuild to take effect — it isn't read live per-request. + +## Known follow-up + +A handful of "See Pro" / "See free plugin" cross-links inside the docs were written for the original plugin repo structure and were adjusted during setup — all internal links were checked and resolve correctly as of this build. If you reorganise the `docs/` folder structure later, re-check cross-plugin links (the free and pro plugin folders link to each other in a few places, e.g. product-attribute-colours ↔ the Pro widget that displays swatches). + +The marketing/"what it does" copy (as opposed to this how-to content) is intended for regular Elementor pages on dotjuice.co.uk, not this docs site — see each plugin's `documentation/marketing/` folder in its own repo. diff --git a/docker-compose.yaml b/docker-compose.yaml new file mode 100644 index 0000000..5fc1c91 --- /dev/null +++ b/docker-compose.yaml @@ -0,0 +1,30 @@ +networks: + proxy: + external: true + +services: + docusaurus: + container_name: ${CONTAINER_NAME} + build: + context: ./site + restart: always + environment: + SITE_URL: ${SITE_URL} + NODE_ENV: production + volumes: + # The markdown source content — edit files here, then + # `docker compose up -d --build` (or just `restart`) to rebuild and + # pick up the changes. Organised as one folder per plugin. + - ./docs:/app/docs + # Rebuilds the static site fresh on every container start (picking up + # whatever is currently in ./docs and the current SITE_URL), then serves + # the result. A few seconds slower to start than pre-built static files, + # but means editing docs never requires touching the image. + command: sh -c "npm run build && npm run serve -- --host 0.0.0.0 --port ${PORT}" + networks: + - proxy + # No host port published — Nginx Proxy Manager reaches this container + # directly by its container name on the shared "proxy" network. Point + # NPM's proxy host at http://${CONTAINER_NAME}:${PORT}. + # ports: + # - "3000:3000" diff --git a/docs/dotjuice-elementor-tools-pro/_category_.json b/docs/dotjuice-elementor-tools-pro/_category_.json new file mode 100644 index 0000000..1328fdd --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Elementor Tools Pro", + "position": 3, + "link": { "type": "doc", "id": "dotjuice-elementor-tools-pro/getting-started" } +} diff --git a/docs/dotjuice-elementor-tools-pro/espocrm-integration.md b/docs/dotjuice-elementor-tools-pro/espocrm-integration.md new file mode 100755 index 0000000..a80b2e8 --- /dev/null +++ b/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. diff --git a/docs/dotjuice-elementor-tools-pro/getting-started.md b/docs/dotjuice-elementor-tools-pro/getting-started.md new file mode 100755 index 0000000..cd8d223 --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/getting-started.md @@ -0,0 +1,46 @@ +# Getting Started + +## Requirements + +Dotjuice Elementor Tools Pro requires: + +- **The free [Dotjuice Elementor Tools](../../../dotjuice-elementor-tools/documentation/marketing/overview.md) plugin**, installed and active — Pro is an add-on, not a standalone plugin. +- **Elementor** (required by the free plugin). +- **WooCommerce**, for every WooCommerce-related widget (all of them except ACF Frontend Form). +- **Advanced Custom Fields (ACF)**, only for the ACF Frontend Form widget. +- **Elementor Pro**, only for Woo Quick View's popup and the [EspoCRM Lead Capture](espocrm-integration.md) integration (Forms is an Elementor Pro feature). + +## Activating your license + +Before any Pro feature works, you need to activate your license key. Go to **Dotjuice → Pro Licence** in your WordPress admin and enter the key from your purchase email. See [Activating Your License](license-activation.md) for the full walkthrough, including what each status message means and what to do if activation fails. + +**Until your license is active, Pro widgets won't appear in the Elementor panel and watermarks stay on Screenshot Capture** — this is expected, and resolves as soon as your key is activated. + +## Finding your widgets + +Once your license is active, open the Elementor editor and look in the **Dotjuice** category — your Pro widgets appear alongside the free plugin's widgets there, each carrying a small Pro badge in the panel. + +If a specific widget is missing: + +- **All WooCommerce widgets** need WooCommerce active. +- **ACF Frontend Form** needs Advanced Custom Fields active. +- **Woo Quick View** needs **Elementor Pro** for its popup functionality — without Elementor Pro, its button falls back to a plain link to the product page instead of opening a popup. + +## Widget guides + +- [Woo Product Filter](widgets/woo-product-filter.md) +- [Woo Cart](widgets/woo-cart.md) +- [Woo Quick View](widgets/woo-quick-view.md) +- [Woo Custom Product Tabs](widgets/woo-custom-product-tabs.md) +- [Woo Add Product Tab](widgets/woo-add-product-tab.md) +- [ACF Frontend Form](widgets/acf-frontend-form.md) + +## Integrations + +- [EspoCRM Lead Capture](espocrm-integration.md) — send Elementor Pro Form submissions straight into EspoCRM. + +## Recommended first steps + +1. Activate your license (above). +2. If you're setting up product filtering, read [Woo Product Filter](widgets/woo-product-filter.md) in full before building your first filter group — it has several settings that interact with each other. +3. If you're setting up Quick View, read [Woo Quick View](widgets/woo-quick-view.md) — it's a two-widget system and needs a specific setup order. diff --git a/docs/dotjuice-elementor-tools-pro/license-activation.md b/docs/dotjuice-elementor-tools-pro/license-activation.md new file mode 100755 index 0000000..5768a56 --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/license-activation.md @@ -0,0 +1,43 @@ +# Activating Your License + +**Dotjuice → Pro Licence** + +## Activating for the first time + +1. Find your license key in your purchase confirmation email — it looks like `DJ-XXXX-XXXX-XXXX-XXXX`. +2. Go to **Dotjuice → Pro Licence** in your WordPress admin. +3. Paste your key into the License Key field and click **Activate Licence**. +4. Once active, the field becomes read-only and the page shows your license status, how many sites you're using out of your plan's limit, and confirms Pro features are unlocked. + +## What each status means + +| Status shown | What it means | +|---|---| +| **Active — lifetime licence** | Fully valid, never expires. | +| **Active — renews [date]** | Fully valid, on a subscription that renews on the date shown. | +| **Active** | Fully valid. | +| **Expired — Pro features are disabled until you renew** | Your license has lapsed. A "Renew your licence" button takes you to your account on the Dotjuice shop. | +| **Revoked — please contact support** | Your license has been cancelled or pulled. Contact support to resolve this. | +| **Key valid but not activated for this site** | Your key is real, but hasn't been activated for this specific site yet — click Activate. | +| **Site limit reached — deactivate another site or upgrade** | You've used up every site activation your plan allows. Deactivate the license on a site you no longer need it on (from your account on the Dotjuice shop, or from that site's own Pro Licence page), or upgrade to a plan with a higher site limit. | +| **Invalid licence key** | The key doesn't match any license on file — check for typos, or that you're using the key for this specific product. | +| **Not activated** | No key has been entered yet. | + +## Other actions on this page + +- **Re-check Status** — forces an immediate recheck against the license server, useful right after renewing or resolving a site-limit issue elsewhere. +- **Deactivate** — removes the license from this specific site, freeing up that site slot for use elsewhere (for example, if you're moving the plugin from a staging site to production). Pro features switch off on this site immediately. + +## What happens while your license isn't active + +Pro widgets don't appear in the Elementor editor's widget panel, and any Pro widgets already placed on a page before your license lapsed won't render on the live site. The free plugin's Screenshot Capture widget keeps its watermark. Everything reactivates automatically the moment your license is valid again — nothing needs to be rebuilt or re-placed. + +## If activation keeps failing + +- Double-check the key was copied correctly, with no extra spaces (copying directly from your purchase email is safest). +- Confirm you're activating the correct product — a key issued for a different Dotjuice product won't activate here. +- If you're confident the key is correct and still see "Invalid licence key" or a persistent connection error, contact support with your order number. + +## Moving to a new site + +If you're relaunching a site on a new domain (for example, moving from a staging URL to your live domain), your existing activation may need to be freed up first. Deactivate the license on the old domain (or from your account on the Dotjuice shop if the old site is no longer reachable), then activate it on the new one. diff --git a/docs/dotjuice-elementor-tools-pro/widgets/_category_.json b/docs/dotjuice-elementor-tools-pro/widgets/_category_.json new file mode 100644 index 0000000..3ad91f3 --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/widgets/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Widgets", + "position": 2 +} diff --git a/docs/dotjuice-elementor-tools-pro/widgets/acf-frontend-form.md b/docs/dotjuice-elementor-tools-pro/widgets/acf-frontend-form.md new file mode 100755 index 0000000..60d8538 --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/widgets/acf-frontend-form.md @@ -0,0 +1,32 @@ +# ACF Frontend Form + +Found in the Elementor panel under **Dotjuice → ACF Frontend form**. Requires Advanced Custom Fields (ACF). + +## How it works + +Place this widget on a template that renders a single post or page — it displays an editable form for **whichever post is currently being viewed**, using ACF's own native form rendering. This widget only works on singular posts/pages (a single product, a single post, a single custom post type entry); it doesn't render anything on archive pages, the homepage, or similar listing pages. + +## Content settings + +| Setting | What it does | +|---|---| +| **ACF Field Groups** | Choose which of your site's ACF field groups should be editable in this form. Nothing renders until at least one is selected. | +| **Enable Title** | Includes the post title as an editable field. | +| **Enable Content** | Includes the main content editor as an editable field. | +| **Submit Button Label** | The text on the form's submit button (default "Update"). | + +## Setting it up + +1. Place the widget on a Single Post, Single Product, or other singular template in your Elementor Theme Builder. +2. Select the ACF field group(s) you want editable. +3. Decide whether the post title and/or content should be editable too. +4. Publish and test by viewing an actual individual post/page that uses this template. + +## ⚠ Important: this widget has no built-in access restriction + +Anyone who can view the page this widget is placed on can submit changes through the form — there's no automatic login requirement or capability check. If you only want logged-in users, specific roles, or the post's author to be able to edit, you'll need to add that restriction yourself: placing the widget inside a members-only page, using a membership/restriction plugin, or a conditional visibility rule in Elementor Pro. Don't place this widget on a fully public page unless open editing is genuinely what you want. + +## Good to know + +- This widget only renders a form when viewing an actual singular post or page — on archives, the homepage, or search results, it won't display anything. +- The uploader for image/file fields uses a simple file picker rather than the full WordPress media library browser. diff --git a/docs/dotjuice-elementor-tools-pro/widgets/woo-add-product-tab.md b/docs/dotjuice-elementor-tools-pro/widgets/woo-add-product-tab.md new file mode 100755 index 0000000..cae5f2c --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/widgets/woo-add-product-tab.md @@ -0,0 +1,27 @@ +# Woo Add Product Tab + +Found in the Elementor panel under **Dotjuice → Woo Add Product Tab**. Requires WooCommerce. + +## How it works + +Place this widget on your Single Product template — it adds one additional tab to WooCommerce's existing native tabs (Description, Additional Information, Reviews), styled to match them automatically since it uses WooCommerce's own tab system. + +## Content settings + +| Setting | Default | What it does | +|---|---|---| +| **Tab Title** | "Additional Info" | The tab's label. | +| **Tab Content** | — | Rich-text content shown inside the tab. | +| **Tab Order** | 50 | Controls where this tab sits relative to WooCommerce's defaults (Description = 10, Additional Information = 20, Reviews = 30). The default of 50 places it after Reviews — lower numbers move it earlier in the tab order. | + +## Setting it up + +1. Add the widget to your Single Product Elementor Theme Builder template. +2. Set your tab title and content. +3. Adjust Tab Order if you want it positioned somewhere other than last. + +## Good to know + +- **If this widget is placed on a shared Single Product template** (which is the normal way to use Elementor Theme Builder — one template applying to every product), every product using that template shows the **identical** tab title and content. This widget doesn't support per-product dynamic content — if you need different tab content on different products, you'll need [ACF Frontend Form](acf-frontend-form.md) with a custom field, or a separate template per product. +- Only one tab per widget instance — add a second instance of this widget if you need two extra tabs. +- You won't see this tab live in the Elementor editor canvas — a placeholder note explains this; preview it by viewing an actual product page on the front end. diff --git a/docs/dotjuice-elementor-tools-pro/widgets/woo-cart.md b/docs/dotjuice-elementor-tools-pro/widgets/woo-cart.md new file mode 100755 index 0000000..e1bd088 --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/widgets/woo-cart.md @@ -0,0 +1,44 @@ +# Woo Cart + +Found in the Elementor panel under **Dotjuice → Woo Cart**. Requires WooCommerce (does not require Elementor Pro). + +## How it works + +Place this widget on your Cart page template. It renders your shopper's current cart — items, coupon box, and totals — built independently of WooCommerce's default cart template, so it's fully restyled from the ground up. + +## Layout settings + +| Setting | Default | What it does | +|---|---|---| +| **Desktop Layout** | 2 columns | Two columns (cart items beside the totals panel) or one column (stacked). | +| **Totals Column Width** | 340px | Two-column layout only — the width of the totals sidebar. | +| **Gap Between Columns** | 32px | Spacing between the two columns. | +| **Show Coupon Field** | On | Displays the coupon code box. Only actually appears if your store's own WooCommerce settings have coupons enabled — if you've disabled coupons store-wide, this setting has no effect. | +| **Show Update Cart Button** | On | See below — this controls how quantity changes are handled. | + +## Instant AJAX updates vs. the Update Cart button + +This is the most important setting on this widget, so it's worth understanding both modes: + +**With "Show Update Cart Button" on (default):** shoppers change a quantity, then click a visible **Update Cart** button (which stays disabled until something has actually changed) to apply it — a standard, familiar cart flow with a normal page action. + +**With "Show Update Cart Button" off:** there's no button at all. Instead, changing any quantity automatically updates that row's subtotal and the whole totals panel via AJAX, a fraction of a second after the shopper stops adjusting it — no page reload, no button click needed. This is the more modern, "instant" feeling option. + +Choose whichever fits your store's style — both are fully functional, it's a matter of preferred shopping experience. + +## Setting it up + +1. Add the widget to your Cart page Elementor Theme Builder template. +2. Choose your column layout and decide on AJAX vs. button-based quantity updates. +3. Work through the style sections below to match your store's design. +4. Test by adding a product to your cart and viewing the page as a real shopper would. + +## Styling + +Extensive styling is available: **Cart Item** rows, **Thumbnail**, **Product Name** (including variation details), **Price/Quantity/Subtotal** (including the quantity stepper's plus/minus buttons), **Remove Button**, **Buttons** (a shared style applying to the coupon Apply button, the Update Cart button, and the Checkout button together), **Form Fields** (the coupon input and quantity field), **Products Box** (the card containing your item rows), **Coupon Box**, and **Totals Box**. If you use the Printful shipping plugin, an additional style section for its shipping calculator appears automatically. + +## Good to know + +- **The "Checkout Button Text" field only affects the editor preview** — on the live cart page with real items, the checkout button's text comes from WooCommerce's own settings rather than this field. The button's *styling* (colour, padding, etc. from the shared Buttons section) does apply live — it's specifically the text on this one field that's preview-only. If you need to change the actual live checkout button text, that's done through WooCommerce's own settings rather than this widget. +- While your own cart is empty, the Elementor editor shows a sample two-item cart purely so you have something to style against — this never appears to real shoppers, who see a genuine "Your cart is empty" message with a link back to your shop. +- Removing an item is instant (AJAX) regardless of the Update Cart Button setting. diff --git a/docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md b/docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md new file mode 100755 index 0000000..7f383da --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md @@ -0,0 +1,46 @@ +# Woo Custom Product Tabs + +Found in the Elementor panel under **Dotjuice → Woo Custom Product Tabs**. Requires WooCommerce. + +## How it works + +Place this widget on your Single Product template — it replaces WooCommerce's entire tabs area with a fully rebuilt, restyled version, including desktop tabs that automatically convert to an accordion on smaller screens. + +**Only need to add one extra tab to WooCommerce's existing tabs, without a full rebuild?** See the lighter-weight [Woo Add Product Tab](woo-add-product-tab.md) instead. + +## Content settings — Tabs + +| Setting | Default | What it does | +|---|---|---| +| **Hide Tab Headings** | Off | Hides the heading text at the top of each tab panel (including WooCommerce's own "Reviews" heading). | +| **Hide Description / Hide Additional Information / Hide Reviews** | Off each | Fully removes that specific default WooCommerce tab — not just visually, it won't render at all. | +| **Custom Tabs** | Empty | A repeater — add as many extra tabs as you need, each with: **Title**, **Content Type** (Text Editor or Elementor Template), **Content** (rich text, for Text Editor), and **Template ID** (for Elementor Template — see below). | +| **Accordion Below (px)** | 768 | The screen width below which tabs switch to an accordion layout. 768 suits tablet-portrait and below, 480 suits mobile-only, and 0 disables the accordion entirely (always shows tabs). | + +## Adding an Elementor Template as a custom tab + +For a custom tab, choosing **Elementor Template** as the Content Type requires entering that template's numeric ID directly (rather than picking it from a list). To find it: + +1. Go to **Templates → Saved Templates** in your WordPress admin (or wherever your Elementor template library lives). +2. Open the template you want to embed, or hover over it in the list. +3. The number in the edit URL (`post=1234`) or shown in your browser's address bar is the Template ID — enter that number into the field. + +## Styling + +**Tab Navigation** — background, spacing, alignment, divider styling, and Normal/Hover/Active states for each tab button (including a separate colour control for the active tab's bottom border, useful for either blending it into the panel or removing the divider line entirely). + +**Panel** — background, typography, padding, border, and shadow for the content area beneath the tabs. + +**Reviews** (hidden if you've turned off the Reviews tab) — review count heading, review card styling, avatar (with an option to hide it, size, and rounding), star rating colours, author/date text, review body text, an optional decorative quote mark, and full styling for the review submission form — its star picker, labels, input fields, and submit button. + +## Setting it up + +1. Add the widget to your Single Product Elementor Theme Builder template. +2. Decide which default tabs to keep, and add any custom tabs you need. +3. Set your Accordion breakpoint based on how your theme handles tablets — 768px is a safe default for most sites. +4. Style the Tab Navigation and Panel sections to match your design, then move on to the Reviews section if you display product reviews. + +## Good to know + +- **If every tab ends up hidden**, nothing renders at all on the live product page — double check at least one tab (default or custom) is visible before publishing. +- Custom tab content using the Elementor Template option needs that template to already be built and published — this widget only embeds it, it doesn't create it. diff --git a/docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md b/docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md new file mode 100755 index 0000000..cb8eea5 --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/widgets/woo-product-filter.md @@ -0,0 +1,55 @@ +# Woo Product Filter + +Found in the Elementor panel under **Dotjuice → Woo Product Filter**. Requires WooCommerce. + +## How it works + +This widget renders one or more filter groups (category, tag, brand, or attribute) and, by default, refreshes your product grid via AJAX whenever a shopper makes a selection — no full page reload needed. It's designed to sit on your Shop page or a category archive, alongside your product grid. + +## Building your filter groups + +Each filter group is one item in the **Filters** repeater. Add as many as you need — one per category/attribute you want shoppers to filter by. + +| Setting | Default | What it does | +|---|---|---| +| **Filter Title** | Empty | An optional heading above this group. | +| **Filter By** | Category | Category, Tag, Brand, or Attribute. | +| **Taxonomy Slug** | — | Only for Attribute — the technical slug of the attribute (e.g. `pa_color`). | +| **Display Type** | List | List (simple clickable list) or Buttons (clickable button/swatch style). | +| **Match Logic** | Match Any | Whether selecting multiple terms in this group should show products matching *any* of them, or *all* of them. | +| **Show products without this attribute** | Yes | Attribute filters only. When a term is selected, decides whether products that don't have this attribute set at all stay visible (Yes) or are hidden (No). | +| **Enable Colour Swatches** | Off | Buttons display only. Shows each term's assigned colour as a clickable swatch instead of a text button — colours come from the [Product Attribute Colours](../../../../dotjuice-elementor-tools/documentation/user-guide/product-attribute-colours.md) settings page in the free plugin. Terms sharing the same colour are merged into a single clickable swatch. | +| **Show this filter** | Always | Always, only when any other filter is selected, or only when a specific other filter type has a selection — see "Dependent filters" below. | +| **Hide unavailable terms** | Off | When on, terms with zero matching products (given the current selection) are removed entirely rather than just visually faded. | + +## Dependent filters + +To build a filter group that only appears once another one is used — for example, showing a "Size" filter only after a category is chosen — set **Show this filter** to "When a specific filter is selected" and choose which filter type triggers it. If the triggering selection is cleared, the dependent group's own selections are cleared too. + +## AJAX & URL settings + +| Setting | Default | What it does | +|---|---|---| +| **Update products with AJAX** | On | Filters refresh the grid in place. Turning this off makes every filter selection a normal page navigation with the filter reflected in the URL instead. | +| **Live update** | Off | AJAX mode only. When on, the grid refreshes automatically the moment a filter is clicked. When off, shoppers make their selections and click an "Apply Filters" button to refresh. | +| **Update browser URL** | On | AJAX mode only. Keeps the URL in sync with the current filter selection as shoppers filter, so the page can be bookmarked, shared, or reloaded and show the same results. | +| **Products container selector** | Empty (auto-detect) | Advanced: the CSS selector of your product grid, if the widget doesn't auto-detect it correctly. Leave empty unless you're troubleshooting a grid that isn't updating. | +| **Contextual filtering** | Off | When placed on a category archive page, scopes filter options and counts to that category's products only, rather than your whole catalogue. | + +## Styling + +Filter Group headings, Buttons (Normal/Hover/Active states), Swatches (Normal/Selected states), and Faded terms (opacity, greyscale, scale for unavailable options, plus a toggle for whether faded/unavailable terms can still be clicked). + +## Setting it up + +1. Add the widget to your Shop page or category archive template, near your product grid. +2. Add a filter group for each way you want shoppers to filter — start with Category, then add Attribute groups for things like colour or size. +3. For colour attributes, set up your colours first on the [Product Attribute Colours](../../../../dotjuice-elementor-tools/documentation/user-guide/product-attribute-colours.md) page, then enable **Enable Colour Swatches** on that filter group. +4. Leave AJAX and URL settings at their defaults for most stores — instant, bookmarkable filtering. +5. Test: apply a filter, copy the URL, and open it in a new tab (or with JavaScript disabled) to confirm it reproduces the same filtered results. + +## Good to know + +- **Filtered URLs work even without JavaScript** — if a shopper shares a filtered link, or your page is cached, the filter still applies correctly on a plain page load, not just via AJAX. This is deliberate and doesn't need any extra setup. +- Colour swatches only work for **Attribute** filter groups (not category/tag/brand), and require colours to already be configured on the Product Attribute Colours page — a term with no colour assigned won't show a meaningful swatch. +- If your product grid doesn't refresh correctly after filtering, check the **Products container selector** field — leaving it empty works for most themes' standard WooCommerce/Elementor product grids, but an unusual custom grid layout may need this set explicitly. diff --git a/docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view-popup.md b/docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view-popup.md new file mode 100755 index 0000000..9f76ed0 --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view-popup.md @@ -0,0 +1,34 @@ +# Woo Quick View Popup + +This widget renders the **content shown inside** a Quick View popup. It only works as part of the full Quick View setup — see [Woo Quick View](woo-quick-view.md) for the complete walkthrough if you haven't set this up yet. + +Found in the Elementor panel under **Dotjuice → Woo Quick View Popup**. Requires WooCommerce. + +## How it works + +Place this widget inside an Elementor popup (nothing else needs to go in that popup — this widget fills it entirely). It renders as an iframe showing whichever product a shopper clicked a Quick View button for. + +## Content settings + +| Setting | Default | What it does | +|---|---|---| +| **Content Source** | Dedicated quick view page (recommended) | **Dedicated**: shows a clean, minimal view of the product — no theme header/footer — using either a template you choose below or a bare WooCommerce product layout. **Legacy**: shows your actual full product page inside the popup, with the option to hide the header/footer via the settings below. | +| **Quick View Template** | Empty (bare WooCommerce layout) | Dedicated mode only. Choose a specific Elementor template to control exactly how the product appears inside the popup, or leave empty to use a plain WooCommerce product layout. | +| **Hide Header** / **Hide Footer** | Off / Off | Legacy mode only. Hides your theme's header and/or footer from within the popup. | + +There's no Style tab — the popup content always fills the popup completely; size it using the popup's own Width/Height settings in Elementor. + +## Hiding specific elements inside the popup + +Add the CSS class `hide-in-qv` to any element in your product template (or your real product page, in Legacy mode) that you don't want shown inside the popup — useful for hiding things like breadcrumbs or a related-products section that don't make sense in a compact popup view. + +## Which mode should you use? + +**Dedicated** (the default and recommended option) is faster and cleaner — it loads a minimal, purpose-built view rather than your entire themed page. Pair it with a purpose-built Elementor template under **Quick View Template** for full control over exactly what shoppers see. + +**Legacy** is useful if you want the popup to look identical to your real product page without building a separate template — but it loads more (the full page, then hides parts of it), so it's a little slower to open. + +## Good to know + +- **This widget must be placed inside an actual Elementor popup**, and that popup must then be selected in the separate Woo Quick View button widget's settings — on its own, on a normal page, it does nothing. +- If you're using a custom **Quick View Template**, note that it replaces WooCommerce's own single-product layout entirely inside the popup — any customisations on your real product page template aren't automatically inherited, since it's a genuinely separate template. diff --git a/docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view.md b/docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view.md new file mode 100755 index 0000000..a94a953 --- /dev/null +++ b/docs/dotjuice-elementor-tools-pro/widgets/woo-quick-view.md @@ -0,0 +1,40 @@ +# Woo Quick View + +Two widgets work together to build Quick View: **Woo Quick View** (this one — the trigger button) and **Woo Quick View Popup** (the content shown inside the popup). Both are needed; this guide covers the full setup. + +Requires WooCommerce. **Requires Elementor Pro** for the popup to actually open — without Elementor Pro, the quick-view button gracefully falls back to a normal link straight to the product page instead, so nothing is ever broken, it simply won't show a popup. + +## How it works, end to end + +1. You build a popup (an Elementor Pro popup content type) containing the **Woo Quick View Popup** widget. +2. You place the **Woo Quick View** widget anywhere you like, and point it at that popup. +3. The Quick View widget then automatically injects a quick-view button onto every product in your product loops (grids, carousels) sitewide — you don't need to manually add a button to each product card. + +## Setting it up + +1. **Create the popup**: in Elementor, create a new Popup (Templates → Popups → Add New in your Elementor library). +2. **Add the Woo Quick View Popup widget** inside it — see [Woo Quick View Popup](woo-quick-view-popup.md) for its settings. Size the popup itself using Elementor's own popup Width/Height settings. +3. **Publish the popup.** +4. **Add the Woo Quick View widget** anywhere on your site (a header, a single instance on any page — it doesn't need to be near your product grid, since it works by injecting buttons into loops sitewide once enabled). +5. Turn on **Enable Quick View**, and select your popup under **Quick View Popup**. +6. Save and check a shop or category page — quick-view buttons should now appear on your product cards. + +## Content settings + +| Setting | Default | What it does | +|---|---|---| +| **Enable Quick View** | Off | The master switch — turns on automatic button injection into every product loop on your site. Nothing happens until this is on. | +| **Quick View on Looped Add to Cart** | Off | For variable products shown in a grid with a "Select options" link (common with Elementor Pro's Loop Grid), replaces that link with a quick-view button too — so shoppers can pick variations without leaving the grid. | +| **Hide on Mobile** | Off | Hides the quick-view button on smaller screens. | +| **Quick View Icon** | Eye icon | The icon used for the button. | +| **Quick View Popup** | — | Which popup contains your Woo Quick View Popup widget — this is the link between the two widgets. **Make sure to select an actual popup you've built with the Quick View Popup widget inside it** — this dropdown lists all your Elementor templates, not only popups, so double check you've selected the right one. | + +## Styling + +Button alignment, and Normal/Hover icon colour and size. + +## Good to know + +- **The button widget and the popup widget must both be set up for anything to happen** — placing just one without the other has no visible effect. +- Hovering over a quick-view button preloads the popup content in the background, so the popup opens close to instantly on click — this preloading only happens when your popup widget is set to its recommended "Dedicated" content mode (see [Woo Quick View Popup](woo-quick-view-popup.md)). +- Buttons keep appearing correctly even after a [Woo Product Filter](woo-product-filter.md) AJAX refresh swaps in new products — no extra setup needed if both widgets are on the same page. diff --git a/docs/dotjuice-elementor-tools/_category_.json b/docs/dotjuice-elementor-tools/_category_.json new file mode 100644 index 0000000..11f7a5f --- /dev/null +++ b/docs/dotjuice-elementor-tools/_category_.json @@ -0,0 +1,5 @@ +{ + "label": "Elementor Tools (Free)", + "position": 2, + "link": { "type": "doc", "id": "dotjuice-elementor-tools/getting-started" } +} diff --git a/docs/dotjuice-elementor-tools/getting-started.md b/docs/dotjuice-elementor-tools/getting-started.md new file mode 100755 index 0000000..b9f9e8e --- /dev/null +++ b/docs/dotjuice-elementor-tools/getting-started.md @@ -0,0 +1,42 @@ +# Getting Started + +## Requirements + +Dotjuice Elementor Tools requires **Elementor** (the free page builder plugin) to be installed and active. It doesn't require WooCommerce or ACF, but several widgets only appear once those plugins are active too — see [Finding your widgets](#finding-your-widgets) below. + +## Finding your widgets + +Open any page in the Elementor editor and look for the **Dotjuice** category in the widgets panel on the left. Every widget from this plugin lives there. + +If a widget you expect to see is missing: + +- **All WooCommerce-related widgets** (anything with "Woo" in the name, plus **Woo Taxonomy List**) only appear once **WooCommerce** is installed and active — even Woo Taxonomy List, which can be used for non-shop content like blog categories, only shows up with WooCommerce present. If you want a general-purpose taxonomy list widget on a site without WooCommerce, install WooCommerce or get in touch with support. +- The **Image Carousel Transform** widget only has a visible effect on pages that also use Elementor Pro's native Image Carousel widget elsewhere. + +## Where the plugin's settings live + +In your WordPress admin menu, under **Dotjuice**: + +- **Elementor Tools** — the plugin's own dashboard (Getting Started, Widgets overview, System Status, Support) +- **Screenshot API** — required setup for the Screenshot Capture widget (see [Screenshot API Settings](screenshot-api-settings.md)) +- **WooCommerce Hacks** — account page tweaks and product attribute colours (only visible with WooCommerce active — see [WooCommerce Account Settings](woocommerce-account-settings.md) and [Product Attribute Colours](product-attribute-colours.md)) + +## Recommended first steps + +1. If you plan to use **Screenshot Capture**, set up your API key first — see [Screenshot API Settings](screenshot-api-settings.md). The widget won't display anything without it. +2. If you run a WooCommerce store, review [WooCommerce Account Settings](woocommerce-account-settings.md) — most stores end up wanting at least one of these tweaks (hiding unused account tabs, excluding a category from the shop page). +3. Browse the widget guides below for the ones relevant to your build. + +## Widget guides + +- [Screenshot Capture](widgets/screenshot-capture.md) +- [Dark Mode Toggle](widgets/dark-mode-toggle.md) +- [Keyword Linker](widgets/keyword-linker.md) +- [Markdown Widget](widgets/markdown-widget.md) +- [Image Carousel Transform](widgets/image-carousel-transform.md) +- [Woo Add to Cart Transform](widgets/woo-add-to-cart-transform.md) +- [Woo Categories Transform](widgets/woo-categories-transform.md) +- [Extended Product Loop](widgets/extended-product-loop.md) +- [Woo My Account Transform](widgets/woo-my-account-transform.md) +- [Woo Page Numbers](widgets/woo-page-numbers.md) +- [Woo Taxonomy List](widgets/woo-taxonomy-list.md) diff --git a/docs/dotjuice-elementor-tools/product-attribute-colours.md b/docs/dotjuice-elementor-tools/product-attribute-colours.md new file mode 100755 index 0000000..78de172 --- /dev/null +++ b/docs/dotjuice-elementor-tools/product-attribute-colours.md @@ -0,0 +1,26 @@ +# Product Attribute Colours + +**Dotjuice → WooCommerce Hacks → Attribute Colours** (only visible with WooCommerce active) + +## What this does + +Lets you assign a hex colour to each term of any product attribute on your store (Colour, Material, or any custom attribute you've created). This is a configuration page — see the note below about where these colours are actually displayed. + +## Setting a colour + +1. Choose the attribute you want to configure from the dropdown at the top (e.g. "Colour"). +2. Every term for that attribute is listed in a table, each with a colour picker and a matching hex code field — you can use either; they stay in sync. +3. Enter or pick a colour for each term you want to configure. A "Clear" button next to each row removes its colour. +4. Save. + +## Sharing one colour across several terms + +If several terms should display as the same swatch colour (for example, "Ash", "Carbon Grey", and "Slate" all rendering as the same grey), just give them the identical hex value. The table shows a "Shared" indicator next to terms that currently share a colour with others, so you can see at a glance which terms are grouped together. + +## Sorting the list + +Use the **Sort by** control (Name or Hex Value) to reorder the table while you work — sorting by hex value groups terms with the same colour together visually, useful for checking your "shared colour" groupings are set up the way you intended. + +## ⚠ Where these colours actually appear + +This page only **stores** the colour assignments — it doesn't display them anywhere on its own. To show them as clickable colour swatches on your product pages, you need the **Woo Add to Cart Transform** widget's "Show Colour Swatches" option, which is a [Dotjuice Elementor Tools Pro](../dotjuice-elementor-tools-pro/getting-started.md) feature. In the free version, you can fully configure your colours here ready for when you upgrade, but your product options will display as plain buttons rather than colour swatches until Pro is active. diff --git a/docs/dotjuice-elementor-tools/screenshot-api-settings.md b/docs/dotjuice-elementor-tools/screenshot-api-settings.md new file mode 100755 index 0000000..e84992d --- /dev/null +++ b/docs/dotjuice-elementor-tools/screenshot-api-settings.md @@ -0,0 +1,29 @@ +# Screenshot API Settings + +**Dotjuice → Screenshot API** + +This page configures the credentials the [Screenshot Capture](widgets/screenshot-capture.md) widget needs to function, and lets you manage the local cache of captured screenshots. + +## Setting up your API key + +1. Sign up for a Screenshot Machine account and get an API key (a link to their site is provided on the settings page). +2. Paste your **API Key** into the field and save. A warning banner at the top of the page will disappear once a key is saved. +3. If your Screenshot Machine account has a **Secret Key** configured for additional request security, enter it in the optional **Secret Key** field too — most accounts don't need this. + +Until an API key is entered, every Screenshot Capture widget on your site will fail to display an image. + +## Cache management + +This section shows: + +- How many screenshots are currently cached +- Their total size on disk +- Where they're stored (inside your uploads folder) +- A **Clear All Cached Screenshots** button + +Clearing the cache deletes every cached screenshot file and removes the corresponding entries from your Media Library. Every widget will re-capture its screenshot (spending a fresh API call) the next time its page is viewed. Use this if you've made site-wide changes to target pages and want everything refreshed at once, rather than refreshing screenshots one at a time from the editor. + +## Things to know + +- Every screenshot capture — whether from a visitor loading an uncached page, or your own manual refresh — counts as one billed API call against your Screenshot Machine plan. Keep this in mind if you have many Screenshot Capture widgets with a low or zero Cache Limit. +- The Secret Key field is optional and only relevant if you've specifically enabled request signing in your Screenshot Machine account settings. diff --git a/docs/dotjuice-elementor-tools/widgets/_category_.json b/docs/dotjuice-elementor-tools/widgets/_category_.json new file mode 100644 index 0000000..3ad91f3 --- /dev/null +++ b/docs/dotjuice-elementor-tools/widgets/_category_.json @@ -0,0 +1,4 @@ +{ + "label": "Widgets", + "position": 2 +} diff --git a/docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md b/docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md new file mode 100755 index 0000000..103f2a0 --- /dev/null +++ b/docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md @@ -0,0 +1,34 @@ +# Dark Mode Toggle + +Found in the Elementor panel under **Dotjuice → Dark Mode Toggle**. + +## How it works + +This widget renders a small clickable icon. Clicking it adds a dark-mode class to your entire site and swaps Elementor's four Global Color variables (Primary, Secondary, Text, Accent) to the dark-mode values you configure on the widget. It remembers the visitor's choice, so it stays applied on their next visit. + +**Important:** this widget only changes colors for elements styled using Elementor's Global Colors. If part of your design uses a hardcoded color instead of a Global Color, that part won't respond to dark mode. + +## Content settings + +| Setting | Default | What it does | +|---|---|---| +| **Light Mode Icon** | Moon icon | The icon shown when the site is currently in light mode (click to switch to dark). | +| **Dark Mode Icon** | Sun icon | The icon shown when the site is currently in dark mode (click to switch back to light). | +| **Icon Color / Hover Color** | — | Styling for the toggle icon itself. | +| **Icon Size** | — | Responsive sizing for the toggle icon. | + +## Dark Mode Colors (Style tab) + +Four color fields — **Primary**, **Secondary**, **Text**, and **Accent** — define what your site looks like once dark mode is switched on. Set each to the dark equivalent of the matching Elementor Global Color. If you leave any of these blank, a sensible built-in dark default is used instead. + +## Setting it up + +1. Add the widget somewhere visible and consistent — a header or footer works well, so it's reachable from every page. +2. Under the Style tab, set your four Dark Mode Colors to a palette that works well as a dark theme. +3. Save and test: click the toggle on the live site and check that the elements using your Global Colors switch correctly. + +## Good to know + +- **Whichever toggle instance was clicked most recently determines the colors used site-wide.** If you place more than one Dark Mode Toggle widget with different color settings, the last one clicked "wins" for the whole site until another is clicked. For a single consistent dark mode, use the same color settings on every instance, or better, only place the widget in one shared location like your header. +- You can deep-link directly into dark mode by adding `?dark=0` to any URL (or `?dark=1`, `?dark=2`, etc. if there's more than one toggle instance on that specific page) — useful for sharing a dark-mode preview link. +- The dark mode choice is remembered per browser (not per WordPress account), so it persists across visits on the same device but doesn't follow a visitor between devices. diff --git a/docs/dotjuice-elementor-tools/widgets/extended-product-loop.md b/docs/dotjuice-elementor-tools/widgets/extended-product-loop.md new file mode 100755 index 0000000..2a10a25 --- /dev/null +++ b/docs/dotjuice-elementor-tools/widgets/extended-product-loop.md @@ -0,0 +1,31 @@ +# Extended Product Loop + +Found in the Elementor panel under **Dotjuice → Extended Product Loop**. Requires WooCommerce. + +## How it works + +This widget renders its own product grid — separate from Elementor's or WooCommerce's native product loop widgets. It shows all your regular published products, plus an extra tile for every individual product variation that has a value set for the attribute you choose. Each tile shows that variation's own image, name, and price, linking through to the parent product page. + +## Content settings + +| Setting | Default | What it does | +|---|---|---| +| **Attribute Name** | `pa_color` | The attribute taxonomy to pull variations from, using its technical slug (WooCommerce attributes are typically prefixed `pa_`, e.g. `pa_color`, `pa_size`). | + +There's no Style tab on this widget — the grid uses WooCommerce's standard product-grid CSS classes, so it inherits your theme's existing product grid styling. + +## What to expect in the grid + +If a product has three variations matching your chosen attribute (say, three colours), it can appear as **up to four tiles**: the parent product once, plus one tile per matching variation. This is intentional — it's what makes a "shop by colour" browsing experience possible — but it's worth knowing in advance so it doesn't look like a duplication bug when you first set it up. + +**This widget's tiles show image, name, and price only** — no Add to Cart button, sale badges, or star ratings, since the grid is built independently of WooCommerce's standard loop template. Link the tile through to the product page for the full buying experience. + +## Setting it up + +1. Decide which attribute you want to browse by (commonly colour or size) and find its technical slug — check **Products → Attributes** in your WordPress admin, or look at the attribute's edit URL. +2. Enter that slug into **Attribute Name**. +3. Place the widget on a page and confirm the variation tiles appear as expected. + +## Good to know + +- If the attribute slug you enter doesn't exist on your store, the widget quietly falls back to showing only your regular product list — no error is shown, so double-check your spelling if variation tiles aren't appearing. diff --git a/docs/dotjuice-elementor-tools/widgets/keyword-linker.md b/docs/dotjuice-elementor-tools/widgets/keyword-linker.md new file mode 100755 index 0000000..fd83608 --- /dev/null +++ b/docs/dotjuice-elementor-tools/widgets/keyword-linker.md @@ -0,0 +1,33 @@ +# Keyword Linker + +Found in the Elementor panel under **Dotjuice → Keyword Linker**. + +## How it works + +This widget doesn't display anything visible on the page itself — it works in the background, scanning your post and page content for the keywords you've defined and converting matching occurrences into links. Add it once to a template that renders post content (a Single Post or Single Page template), and it applies to every post/page using that template. + +Matching happens inside paragraph and heading text only — text inside list items, tables, or other structural elements isn't scanned. Matching is whole-word and case-insensitive, and any text that's already part of an existing link is left alone. + +## Content settings — Keyword Links + +A repeater list; add one row per keyword you want linked. + +| Setting | What it does | +|---|---| +| **Keyword** | The exact word or phrase to search for. Matches are whole-word only (so "cat" won't match "category") and case-insensitive. | +| **Link** | The destination URL, with options to open in a new tab and/or add a "nofollow" attribute. | +| **Bold** | Makes the generated link bold. | +| **Link All Occurrences** | If on, every matching occurrence on the page gets linked. If off, only the first few (see Max Links below). | +| **Max Links** | Only shown when "Link All Occurrences" is off. The maximum number of times this specific keyword gets linked per page (1–50, default 3). | + +## Setting it up + +1. Add the widget to a template that renders your post/page content (typically your Single Post or Single Page Elementor template — this is a "Theme Builder" style template in Elementor, not a specific individual post). +2. Add a row for each keyword you want automatically linked, with its destination URL. +3. Save and visit a post that contains one of your keywords — it should now appear as a link. + +## Good to know + +- **This widget needs to sit on a template that actually renders post content** — placing it on a page with no post content being displayed does nothing, since it works by intercepting WordPress's content output. +- The first occurrence of a keyword found in a matching heading or paragraph keeps its original capitalization in the resulting link — you don't need to match the exact case when defining the keyword. +- Links are only ever added inside `

` and heading tags — if your target text lives inside a list, table, or custom block markup, it won't be matched. diff --git a/docs/dotjuice-elementor-tools/widgets/markdown-widget.md b/docs/dotjuice-elementor-tools/widgets/markdown-widget.md new file mode 100755 index 0000000..6c779a7 --- /dev/null +++ b/docs/dotjuice-elementor-tools/widgets/markdown-widget.md @@ -0,0 +1,27 @@ +# Markdown Widget + +Found in the Elementor panel under **Dotjuice → Markdown**. + +## How it works + +The widget fetches the Markdown file you specify directly in the visitor's browser and converts it to HTML on the fly. Because the fetch happens in the browser, the source file needs to allow cross-origin requests — raw file URLs from GitHub (`raw.githubusercontent.com`) work well; a URL that isn't set up to allow this will fail to load, with a note in the browser's developer console. + +## Content settings + +| Setting | What it does | +|---|---| +| **Markdown File URL** | The direct URL to the raw Markdown file (not a formatted preview page — for GitHub, use the "Raw" file link, not the normal file view). | + +## Styling + +| Setting | What it does | +|---|---| +| **Text Color** | Sets the base text color for the rendered content. | + +The Markdown is converted to plain semantic HTML (headings, paragraphs, lists, code blocks, links) with no additional classes — headings, code blocks, and other elements will take on whatever styling your theme already applies to those standard HTML tags. If you want the rendered Markdown to look a specific way, style it through your theme's typography settings for headings, lists, and `

`/`` blocks, since this widget doesn't apply its own detailed formatting beyond the base text color.
+
+## Good to know
+
+- **Use the raw file URL, not a formatted view.** For a GitHub file, click "Raw" on the file page and use that URL — the normal GitHub file-viewer page returns an HTML page, not the Markdown source, and won't render correctly.
+- The content loads via JavaScript after the page loads, so it won't appear in "view source" — this is expected and doesn't affect what visitors see.
+- If nothing appears, check your browser's developer console: the two most common causes are an incorrect URL (view page instead of raw file) or the source not allowing cross-origin requests from your domain.
diff --git a/docs/dotjuice-elementor-tools/widgets/screenshot-capture.md b/docs/dotjuice-elementor-tools/widgets/screenshot-capture.md
new file mode 100755
index 0000000..a9e05a2
--- /dev/null
+++ b/docs/dotjuice-elementor-tools/widgets/screenshot-capture.md
@@ -0,0 +1,40 @@
+# Screenshot Capture
+
+Found in the Elementor panel under **Dotjuice → Screenshot Capture**.
+
+## Before you start: set up your API key
+
+This widget uses the Screenshot Machine API to capture screenshots, which requires a free or paid API key from their service. Go to **Dotjuice → Screenshot API** in your WordPress admin and enter your key — the widget won't display anything until this is done. See [Screenshot API Settings](../screenshot-api-settings.md) for full setup details.
+
+## Content settings
+
+| Setting | Default | What it does |
+|---|---|---|
+| **URL** | — | The web address to screenshot. |
+| **Refresh Screenshot** button | — | Editor only. Forces a brand-new capture immediately, bypassing the cache — use this after the target page has changed. |
+| **Full Page** | Off | Captures the entire scrollable page rather than just the visible viewport. |
+| **Cache Limit (days)** | 0 | How many days a captured screenshot stays cached before it's automatically re-captured on a visitor's page load. `0` means it's captured once and never automatically refreshed — use the Refresh button or clear the cache manually (see below) to update it. |
+| **Device** | Desktop | Desktop, Tablet, or Phone — captures at that device's typical screen dimensions. |
+| **Zoom** | 100% | Zoom level applied during capture, from 50% to 200%. |
+| **Click Element** | Empty | A CSS selector (or comma-separated list) to click before the screenshot is taken — useful for dismissing a cookie banner or opening a menu first. |
+| **Selector** | Empty | Crop the capture to a specific element on the target page, given as a CSS selector. |
+| **Delay (ms)** | 3000 | How long to wait after the page loads before capturing — increase this for pages with animations or content that loads in after the initial page load. |
+
+## Display settings (Style tab)
+
+- **Width / Height** — the maximum size of the screenshot display area.
+- **Website Link** — if set, clicking the screenshot goes to this URL instead of the page that was captured.
+- **Show Lightbox** — opens the screenshot in a lightbox on click (only applies if Website Link is empty). Multiple Screenshot Capture widgets on the same page with this enabled become one swipeable lightbox gallery together.
+- **Scroll Speed** — for full-page captures only: how fast the image auto-scrolls to reveal the whole page (lower is faster).
+- **Border**, **Box Shadow**, **CSS Filters**, and a **Transform** popover (rotate, scale, offset, opacity) are available for both the normal and hover states, exactly like Elementor's native Image widget.
+
+## Managing your screenshot cache
+
+On the **Dotjuice → Screenshot API** settings page, a Cache Management panel shows how many screenshots are currently cached and their total size, with a **Clear All Cached Screenshots** button to force every screenshot on your site to be re-captured on next view. Screenshots are stored in your Media Library, so clearing the cache removes them from there too.
+
+## Good to know
+
+- **Every capture uses one API call**, whether triggered by a visitor's first view of an uncached page, or the editor's Refresh button. With Cache Limit set to 0 (the default), a given screenshot is only captured once — subsequent visitors see the cached version until you manually refresh it or your Cache Limit expires it.
+- **The first visitor to an uncached page waits for the live capture** to complete before the page finishes loading. If you're about to publish a page with several uncached screenshots, visit it yourself first (or use the editor's Refresh button on each one) so the cache is warm before real visitors arrive.
+- The editor never triggers an automatic capture while you're designing, specifically to avoid spending API calls while you work — you'll see a placeholder instead until you click Refresh.
+- Changing **Cache Limit**, **Delay**, **Click Element**, or **Selector** on an already-cached screenshot won't take effect until you use the Refresh button — these settings affect how a new capture is taken, not the one already cached.
diff --git a/docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md b/docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md
new file mode 100755
index 0000000..1211c3d
--- /dev/null
+++ b/docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md
@@ -0,0 +1,31 @@
+# Woo Add to Cart Transform
+
+Found in the Elementor panel under **Dotjuice → Woo Add To Cart transform**. Requires WooCommerce.
+
+## How it works
+
+Place this widget on your single product template (typically inside your Elementor Theme Builder's Single Product template, near where the product form appears). It finds WooCommerce's native variation `