jandieman/dotjuice-plugin-docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Docs pass: add widget screenshots and expand the user guides

Browse Source 
Add 21 screenshots across the Elementor Tools docs and rework the pages
around them: clearer opening lines, settings tables that state defaults,
and callouts for the parts people trip over. Also refreshes the Pro
getting-started, Custom Product Tabs and Product Filter pages, plus the
matching marketing copy.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
This commit is contained in:
Johan
2026-07-31 06:13:57 +00:00
parent 1d9b26b108
commit f4838865c9
43 changed files with 672 additions and 253 deletions
Download Patch File Download Diff File Expand all files Collapse all files

63
docs/dotjuice-elementor-tools/widgets/dark-mode-toggle.md
View File

@@ -1,55 +1,68 @@
# Dark Mode Toggle
A front-end light/dark switch that recolours your site by overriding Elementor's global colours.
Found in the Elementor panel under **Dotjuice → Dark Mode Toggle**.
![The Dark Mode Toggle widget controls in the Elementor panel](../assets/img/dark-mode-toggle-controls.png)
*Screenshot: the widget selected in the editor with the **Icons** section open, showing the Normal/Dark icon pickers and colour controls.*
## How it works
This widget renders a small clickable icon. Clicking it adds a dark-mode class to your entire site and swaps your global colours to the dark-mode values you configure on the widget. It remembers the visitor's choice, so it stays applied on their next visit.
The widget renders a small clickable icon. Clicking it adds a dark-mode class to your entire site and swaps your global colours for the dark-mode values you configure on the widget. The choice is stored in the visitor's browser, so it survives navigation and returns on their next visit.
It works with **both** of Elementor's global-colour systems:
- **Legacy 3.x global colours** — the four classic Global Colors (Primary, Secondary, Text, Accent) used by traditional Elementor widgets.
- **Elementor 4.x global variables** — the named colour variables (e.g. `red`, `sea-green`) introduced with the newer atomic/v4 widgets, defined under **Site Settings → Global Variables**.
- **Elementor 4.x global variables** — the named colour variables (e.g. `red`, `sea-green`) introduced with the newer atomic widgets, defined under **Site Settings → Global Variables**.
Because modern pages often mix older widgets (which read the legacy colours) with newer atomic widgets (which read 4.x variables), the widget can override both at once from a single toggle.
Modern pages commonly mix older widgets (which read the legacy colours) with newer atomic widgets (which read 4.x variables), so the widget can override both at once from a single toggle.
**Important:** this widget only changes colours for elements styled using a global colour or global variable. Anything using a hardcoded colour won't respond to dark mode — the more consistently your design uses global colours/variables, the more complete the effect.
:::caution The single most important thing to understand
Dark mode only changes elements styled with a **global colour or global variable**. Anything using a hardcoded hex value won't respond at all. If your toggle seems to "only half work", that's almost always the cause — the more consistently your design uses globals, the more complete the effect.
:::
## Content settings
## Content settings — Icons
| 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. |
| **Normal Mode Icon** | Moon | Shown while the site is in light mode. Clicking it switches to dark. |
| **Dark Mode Icon** | Sun | Shown while the site is in dark mode. Clicking it switches back to light. |
| **Icon Color** | — | Colour of the toggle icon itself (not affected by dark mode). |
| **Hover Color** | — | Icon colour on hover. |
| **Icon Size** | 24px | Responsive — set a different size per breakpoint if needed. |
## Dark Mode Colors (Style tab)
## Dark Mode Colors
At the top, **Global Colour System** decides which colour systems dark mode overrides:
**Global Colour System** decides which colour systems the toggle overrides:
| Choice | What it does |
|---|---|
| **Both** *(default)* | Applies the legacy four colours **and** your chosen 4.x variable overrides together — best for pages that mix old and new widgets. |
| **Legacy only** | Overrides just the four classic Global Colors. |
| **Variables only** | Overrides just the 4.x global variables, leaving the legacy four untouched. |
| **Both** *(default)* | Applies the legacy four colours **and** your 4.x variable overrides together. Best for pages mixing old and new widgets. |
| **Legacy only — Elementor 3.x** | Overrides just Primary, Secondary, Text and Accent. |
| **Variables only — Elementor 4.x** | Overrides just the global variables, leaving the classic four untouched. |
**Legacy 3.x global colors** — four colour fields (**Primary**, **Secondary**, **Text**, **Accent**) define the dark equivalent of each classic Global Color. Leave any blank to use a sensible built-in dark default.
**Legacy 3.x global colors** — four colour fields (**Primary**, **Secondary**, **Text**, **Accent**) define the dark equivalent of each classic Global Color. Leave any blank to fall back to a sensible built-in dark default.
**Elementor 4.x global variables** — add a row for each variable you want to change in dark mode: pick the variable from the list of your site's global variables, then set its dark-mode colour. The dark value can be a plain colour, or a reference to one of your palette colours. Add as many rows as you need.
**Elementor 4.x global variables** — a repeater. Add one row per variable you want to change: pick the variable from your site's list, then set its dark-mode colour. Add as many rows as you need; variables you don't list keep their normal values.
> New variables you create *after* opening the editor won't appear in the list until you reload the editor, because Elementor builds the widget's options once when the editor loads.
![The Dark Mode Colors section with variable override rows](../assets/img/dark-mode-toggle-colours.png)
*Screenshot: the **Dark Mode Colors** section showing the Global Colour System dropdown, the four legacy colour fields, and two or three variable override rows.*
:::note
New variables created *after* you opened the editor won't appear in the dropdown until you reload it — Elementor builds the widget's option list once, when the editor loads.
:::
## 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, choose your **Global Colour System** (leave on **Both** if your site mixes widget types).
3. Set your Legacy dark colours and/or add variable rows for a palette that works well as a dark theme.
4. Save and test: click the toggle on the live site and confirm the elements using your global colours/variables switch correctly.
1. Add the widget somewhere reachable from every page — a header or footer is the usual choice.
2. Choose your **Global Colour System**. Leave it on **Both** unless you know your site uses only one widget generation.
3. Set the legacy dark colours, and/or add a variable row for each global variable that needs a dark value.
4. Save, then click the toggle on the live site and check that everything using globals switches cleanly.
## Good to know
- **Whichever toggle instance was clicked most recently determines the colours used site-wide.** If you place more than one Dark Mode Toggle with different settings, the last one clicked "wins" for the whole site until another is clicked. For a single consistent dark mode, use the same settings on every instance, or place the widget in one shared location like your header.
- If you change the widget's colour settings after already switching dark mode on, toggle it off and back on once (or clear the browser's site data) so it re-reads the new values — the last-used colours are cached in the browser for speed.
- 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.
- **The most recently clicked toggle determines the colours used site-wide.** If you place several toggles with different settings, the last one clicked wins until another is clicked. For consistency, either use identical settings everywhere or place a single toggle in a shared header.
- **Changed your colours after already switching dark mode on?** Toggle it off and on once, or clear the browser's site data. The last-used colours are cached in the browser for speed, so a stale set can linger.
- **You can deep-link into dark mode** by adding `?dark=0` to any URL — or `?dark=1`, `?dark=2` and so on where a page holds more than one toggle. Handy for sharing a dark-mode preview.
- **The preference is per browser, not per WordPress account.** It persists across visits on the same device but doesn't follow a visitor to another device or browser.

51
docs/dotjuice-elementor-tools/widgets/keyword-linker.md
View File

@@ -1,33 +1,52 @@
# Keyword Linker
Turn chosen words into links automatically, across every post using a template.
Found in the Elementor panel under **Dotjuice → Keyword Linker**.
![The Keyword Linker repeater with several keyword rows](../assets/img/keyword-linker-controls.png)
*Screenshot: the widget's **Keyword Links** repeater expanded, showing two or three keyword rows with their URL, Bold and Link all occurrences settings.*
## 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.
This widget renders nothing visible. It works in the background: it hooks into WordPress's content output, scans for the keywords you've defined, and converts matching occurrences into links. Add it once to a template that renders post content — a Single Post or Single Page Theme Builder template — and it applies to every post or 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.
That "invisible widget on a template" model is the part people trip over. You are not adding it to one article; you are adding it to the template all your articles share.
**Matching rules:**
- Only text inside paragraph (`<p>`) and heading tags is scanned. Text inside list items, tables, or custom block markup is left alone.
- Matching is **whole-word**, so `cat` will not match `category`.
- Matching is **case-insensitive**, and the matched text keeps its original capitalisation in the resulting link — you don't need to define both "Elementor" and "elementor".
- Text that is already inside a link is never re-linked, so you won't get nested anchors.
## Content settings — Keyword Links
A repeater list; add one row per keyword you want linked.
A repeater. 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 | Default | What it does |
|---|---|---|
| **Keyword** | — | The word or phrase to look for. Whole-word, case-insensitive. |
| **URL** | — | Where the link points. Supports Elementor's usual open-in-new-tab and nofollow options. |
| **Bold link text** | Off | Renders the generated link in bold. |
| **Link all occurrences** | Off | On: every match on the page is linked. Off: only the first few, capped by Max links. |
| **Max links** | 3 | Only shown when **Link all occurrences** is off. How many times this keyword may be linked on a single page (1–50). |
:::tip Why you usually want the cap
Linking every occurrence of a common word reads as spam to both visitors and search engines. The default of three is deliberate — it catches the keyword early in the article where it matters, and leaves the rest as plain text.
:::
## 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.
1. Open the Theme Builder template that renders your post content — typically **Single Post**. Do not add this to an individual page.
2. Drop the Keyword Linker widget anywhere on that template. Position is irrelevant; it renders nothing.
3. Add a row per keyword, each with its destination URL.
4. Decide per keyword whether to link every occurrence or cap it.
5. Save, then visit a post containing one of your keywords and confirm the link appears.
## 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 `<p>` and heading tags — if your target text lives inside a list, table, or custom block markup, it won't be matched.
- **It must sit on a template that actually renders post content.** On a page with no post content being output there is nothing to scan, so nothing happens. This is the most common reason it appears not to work.
- **Links are only added inside `<p>` and heading tags.** If your target text lives in a list, table, or a custom block's markup, it won't be matched — move the text into a paragraph if you need it linked.
- **Keywords are matched independently.** If two keywords overlap in the same sentence, both can be linked; there's no ordering guarantee between them, so avoid defining a keyword that is a substring of another phrase you also link.
- Because it works on rendered output rather than stored content, removing the widget removes every generated link cleanly — your posts are never modified in the database.

75
docs/dotjuice-elementor-tools/widgets/markdown-widget.md
View File

@@ -1,27 +1,80 @@
# Markdown Widget
Render a live Markdown file — a README, changelog, or documentation page — directly in your site, always showing the current version.
Found in the Elementor panel under **Dotjuice → Markdown**.
![The Markdown widget controls in the Elementor panel](../assets/img/markdown-widget-controls.png)
*Screenshot: the widget selected in the editor with the **Settings** section open, showing the Markdown Source dropdown and the Markdown File URL field.*
## 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.
The widget fetches the Markdown file **on your server**, embeds the document in the page, and converts it to HTML in the visitor's browser. Fetched files are cached for 15 minutes.
Because the fetch is server-side, the source does **not** need to permit cross-origin requests. Raw URLs from GitHub, Gitea, or a private self-hosted server all work.
## 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). |
| Setting | Default | What it does |
|---|---|---|
| **Markdown Source** | External URL | Choose between fetching a URL or using a file from the Media Library. |
| **Markdown File URL** | — | Direct URL to the raw Markdown file. Supports dynamic content, so the URL can come from a custom field. |
| **Markdown File** | — | Upload a `.md` file or pick one from the Media Library. Shown when Source is set to Uploaded file. |
:::caution Use the raw file URL
For a GitHub file, click **Raw** and use that URL. The normal file-viewer page returns an HTML page rather than Markdown source, and won't render correctly. The same applies to Gitea and most other Git hosts.
:::
## Styling
| Setting | What it does |
|---|---|
| **Text Color** | Sets the base text color for the rendered content. |
| Setting | Default | What it does |
|---|---|---|
| **Text Color** | `#000000` | Base text colour 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 `<pre>`/`<code>` blocks, since this widget doesn't apply its own detailed formatting beyond the base text color.
The Markdown is converted to plain semantic HTML — headings, paragraphs, lists, code blocks, links — with no extra classes. Those elements inherit whatever styling your theme already applies to standard HTML tags. To control the appearance, style headings, lists and `<pre>`/`<code>` through your theme's typography settings; this widget doesn't impose its own formatting beyond the base text colour.
## Shortcode
Anywhere the widget can't go — a WooCommerce product tab, a text editor, a template — use the shortcode instead:
```
[dj_markdown url="https://example.com/changelog.md"]
```
### Pulling the URL from a custom field
Rather than a fixed URL, point the shortcode at a field name and it reads that field from the post being displayed:
```
[dj_markdown acf_field="changelog_url"]
```
This is the practical way to show a different document per post or product. Add a URL field to your products, place one shortcode in a tab or template, and every product renders its own file.
The field is read from ACF when installed, and falls back to a plain custom field otherwise — so it works either way. ACF **URL**, **Text**, **Link** and **File** field types are all handled.
![A per-product changelog rendered inside a product tab](../assets/img/markdown-widget-product-tab.png)
*Screenshot: a product page with a "Changelog" tab open, showing a rendered Markdown changelog pulled from that product's own field.*
### All attributes
| Attribute | What it does |
|---|---|
| `url` | The Markdown URL to fetch. Takes precedence if both are given. |
| `acf_field` | Name of a field holding the URL. Also accepts `acf-field` or `field`. |
| `post_id` | Read the field from this post instead of the one being displayed. |
| `cache` | Cache lifetime in seconds. Use `cache="0"` to always fetch fresh. |
| `class` | Extra CSS class on the container, for styling. |
`[dj-markdown]` works as an alias if you prefer the hyphen.
:::tip Pairing it with product tabs
The Pro plugin's [Woo Custom Product Tabs](../../dotjuice-elementor-tools-pro/widgets/woo-custom-product-tabs.md) runs shortcodes in its custom tab content, which is what makes the per-product changelog pattern above work.
:::
## 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.
- **Only http:// and https:// URLs are accepted.** Other schemes are rejected, so a Markdown file must be reachable over the web — a local file path won't work.
- **The rendered HTML is produced by 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 and you're logged in as an editor or administrator**, the widget and shortcode both print the reason directly on the page. Visitors never see those messages — they get an HTML comment instead.
- **Edits to a source file take up to 15 minutes to show** because of the cache. Add `cache="0"` to the shortcode while you're setting things up, then remove it.

72
docs/dotjuice-elementor-tools/widgets/screenshot-capture.md
View File

@@ -1,40 +1,68 @@
# Screenshot Capture
Live screenshots of any website, captured through the Screenshot Machine API and cached in your Media Library.
Found in the Elementor panel under **Dotjuice → Screenshot Capture**.
![The Screenshot Capture widget's capture settings](../assets/img/screenshot-capture-controls.png)
*Screenshot: the widget selected in the editor showing the **Capture settings** section — URL field, Refresh button, Full Page toggle, Device, Zoom and Delay controls.*
## 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.
This widget calls the Screenshot Machine API, which needs an API key. Go to **Dotjuice → Integrations** in your WordPress admin and enter your key on the Screenshot API tab. **The widget renders nothing until this is done.** Full instructions are in [Screenshot API Settings](../screenshot-api-settings.md).
## Content settings
## How it works
When a visitor loads a page containing an uncached screenshot, the plugin requests a capture from the API, saves the resulting image into your Media Library, and serves it from there afterwards. Later visitors get the stored image with no API call at all.
This means two things worth planning around:
- **Captures cost API calls.** Your key has a quota; each fresh capture spends one.
- **The first visitor to an uncached screenshot waits for it.** The capture happens during their page load.
The editor deliberately never triggers an automatic capture while you design — it shows a placeholder instead, so building a page doesn't burn through your quota. Use the **Refresh Screenshot** button when you actually want an image.
## Capture 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. |
| **Website URL** | — | The address to capture. |
| **Refresh Screenshot** | — | Editor only. Forces a fresh capture immediately, bypassing the cache. Use after the target page changes. |
| **Full Page Screenshot** | Off | Captures the whole scrollable page rather than just the visible viewport. |
| **Cache Limit** | 0 | Days a capture stays cached before being retaken automatically. `0` means capture once and never auto-refresh — you refresh manually. |
| **Device Type** | Desktop | Desktop, Tablet or Phone. Captures at that device's typical dimensions. |
| **Zoom (%)** | 100 | Zoom applied during capture, 50–200%. |
| **Click Element (CSS Selector)** | Empty | A selector (or comma-separated list) clicked before capturing — for dismissing a cookie banner or opening a menu first. |
| **Selector (CSS)** | Empty | Crop the capture to one element on the target page instead of the whole viewport. |
| **Delay (ms)** | 3000 | How long to wait after load before capturing. Increase for pages with animations or late-loading content. |
## Display settings (Style tab)
:::tip Getting a clean capture of a site with a cookie banner
Put the banner's accept-button selector into **Click Element**, and raise **Delay** enough for the banner's dismiss animation to finish. A 3000ms delay with no click usually still catches the banner mid-page.
:::
- **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.
## Display settings
| Setting | What it does |
|---|---|
| **Width / Height** | Maximum display size of the screenshot area. |
| **Link** | If set, clicking the screenshot goes here instead of the captured page. |
| **Display image in lightbox** | Opens the image in a lightbox on click. Only applies when **Link** is empty. Several Screenshot Capture widgets on one page with this on become a single swipeable gallery. |
| **Scroll Speed** | Full-page captures only. Seconds to scroll one screen height on hover — lower is faster. |
**Border**, **Box Shadow**, **CSS Filters** and a **Transform** popover (rotate, scale, offset X/Y, opacity) are all available for both Normal and Hover states, matching 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.
The **Dotjuice → Integrations** page has a Cache Management panel showing how many screenshots are cached and their total size, with a button to clear them all and force every screenshot on the site to re-capture on next view.
![The screenshot cache management panel](../assets/img/screenshot-capture-cache.png)
*Screenshot: the Cache Management panel on the Integrations page, showing the cached count, total size and the clear button.*
Screenshots live in your Media Library, so clearing the cache deletes those attachments 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.
- **Every capture costs one API call** — whether triggered by a visitor hitting an uncached page or by the editor's Refresh button. With Cache Limit at 0, each screenshot is captured once and then reused indefinitely.
- **Warm the cache before launch.** If you're publishing a page with several uncached screenshots, visit it yourself first, or hit Refresh on each widget in the editor, so real visitors don't absorb the capture wait.
- **Changing Cache Limit, Delay, Click Element or Selector does nothing to an already-cached image.** Those settings describe how a *new* capture is taken. Hit Refresh to apply them.
- If a screenshot never appears, check the API key first — an unset or exhausted key is by far the most common cause.

47
docs/dotjuice-elementor-tools/widgets/woo-add-to-cart-transform.md
View File

@@ -1,31 +1,56 @@
# Woo Add to Cart Transform
Rebuild WooCommerce's variation dropdowns as clickable buttons, and style the product form to match your design.
Found in the Elementor panel under **Dotjuice → Woo Add To Cart transform**. Requires WooCommerce.
![The Woo Add To Cart transform controls](../assets/img/woo-add-to-cart-controls.png)
*Screenshot: the widget selected in the editor showing the **Variation buttons** section — Swap to Buttons, Show Colour Swatches, Hide Labels and Button Spacing.*
## 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 `<select>` dropdowns on that page and converts them into a row of clickable buttons.
Place this widget on your Single Product template, near where the product form appears. It finds WooCommerce's native variation `<select>` dropdowns on the page and converts each into a row of clickable buttons.
Shoppers pick "Large" by clicking it rather than opening a dropdown and scrolling — fewer taps on mobile, and every option is visible at a glance.
![Variation buttons on a product page](../assets/img/woo-add-to-cart-frontend.png)
*Screenshot: a live product page showing size and colour options rendered as button rows instead of dropdowns, with one option selected.*
## Content settings
| Setting | Default | What it does |
|---|---|---|
| **Swap to Buttons** | Off | Turns on the dropdown-to-button conversion. Leave this off if you want to keep native WooCommerce dropdowns but still use the price/description styling controls below. |
| **Show Colour Swatches** | Off | **Pro feature.** In the free version, this setting has no visible effect — buttons always display as text. Colour swatches (each button showing its actual colour) require [Dotjuice Elementor Tools Pro](../../../../dotjuice-elementor-tools-pro/documentation/marketing/overview.md). |
| **Hide Labels** | Off | Hides the attribute name label (e.g. "Colour", "Size") next to each button group. |
| **Button Spacing** | 10px | Spacing between buttons within a group. |
| **Swap to Buttons** | Off | Turns on the dropdown-to-button conversion. Leave it off to keep native dropdowns while still using the price and description styling below. |
| **Show Colour Swatches** | Off | **Pro feature.** No visible effect in the free version — buttons always render as text. See below. |
| **Hide Labels** | Off | Hides the attribute name ("Colour", "Size") beside each button group. |
| **Button Spacing** | 10px | Space between buttons within a group. |
## Styling
- **Buttons** — Normal and Selected states, each with text colour, background colour, typography, border, box shadow, and padding, plus a shared border radius.
- **Text** — typography and colour for the product price and short description.
- **Swatch** — sizing, padding, and border controls for colour swatches (only visible in the Pro version, where swatches actually render).
| Section | What it covers |
|---|---|
| **Buttons** | Normal and Selected states — text colour, background, typography, border, box shadow and padding, plus a shared border radius. |
| **Text** | Typography and colour for the product price and short description. |
| **Swatch** | Size, padding and border for colour swatches. Only meaningful in Pro, where swatches actually render. |
Style the **Selected** state distinctly — it's the only feedback a shopper gets that their choice registered.
## Setting up colour swatches (Pro)
Even in the free version, you can pre-configure your swatch colours ready for when you upgrade: go to **Dotjuice → WooCommerce Hacks → Attribute Colours** and assign a colour to each attribute term (e.g. Red, Blue, Green). See [Product Attribute Colours](../product-attribute-colours.md) for the full guide. Once Pro is active and "Show Colour Swatches" is enabled, these assigned colours display automatically.
You can pre-configure swatch colours in the free version, ready for an upgrade. Go to **Dotjuice → WooCommerce Hacks → Attribute Colours** and assign a colour to each attribute term — see [Product Attribute Colours](../product-attribute-colours.md).
Once [Pro](../../dotjuice-elementor-tools-pro/getting-started.md) is active and **Show Colour Swatches** is on, those colours render automatically. Terms sharing a hex value merge into one swatch.
## Good to know
- **Two WooCommerce-wide behaviours are always active once this plugin and WooCommerce are both installed**, regardless of whether you've placed this widget on any page: WooCommerce's default "Clear" reset-selection link is replaced with this widget's version, and per-variation pricing is always shown (rather than only appearing when variations have different prices). These are intentional store-wide improvements, not something you need to configure per page.
- Because the button styling targets WooCommerce's variation markup directly rather than being scoped to just this widget, if a page shows more than one product form (for example, a quick-view popup alongside the main product), the same button styling applies to all of them.
:::caution Two behaviours apply store-wide, with or without this widget
Once this plugin and WooCommerce are both active, these happen everywhere regardless of whether you've placed the widget on any page:
- WooCommerce's default **"Clear" reset-selection link** is replaced with this plugin's version.
- **Per-variation pricing is always shown**, rather than appearing only when variations differ in price.
These are deliberate store-wide improvements, not per-page settings. If you're wondering why a product form changed on a template where you never added the widget, this is why.
:::
- **Button styling targets WooCommerce's variation markup directly** rather than being scoped to this widget instance. If a page shows more than one product form — a quick-view popup alongside the main product, say — the same styling applies to all of them.
- The conversion runs against whatever dropdowns exist at page load. A theme or plugin that injects extra variation fields later won't have those converted.

53
docs/dotjuice-elementor-tools/widgets/woo-categories-transform.md
View File

@@ -1,36 +1,61 @@
# Woo Categories Transform
Turn WooCommerce's plain category tiles into styled, animated cards with overlay text and hover effects.
Found in the Elementor panel under **Dotjuice → Woo Categories Transform**. Requires WooCommerce.
![A styled category grid on the shop page](../assets/img/woo-categories-transform-frontend.png)
*Screenshot: a shop page showing category tiles with overlaid titles on a frosted background, one tile mid-hover with its image scaled.*
## How it works
Place this widget on any page that shows WooCommerce's product category tiles — typically your Shop page when it's set to display subcategories. It restructures the tile markup into styleable wrapper sections and applies the styling you configure below to every category tile on that page.
Place this widget on any page that displays WooCommerce's product category tiles — usually the Shop page when it's set to show subcategories. It restructures the tile markup into styleable wrapper sections, then applies your styling to every category tile on that page.
This widget has no Content tab — every setting lives under Style.
**This widget has no Content tab.** Every setting lives under Style, because it isn't producing content of its own — it's restyling markup WooCommerce already outputs.
## Box styling
Border style, colour, width, radius, background colour, and padding for the overall category tile.
Border style, colour, width and radius, background colour, and padding for the tile as a whole.
## Image styling
- **Overflow** — controls whether hover transforms are clipped to the image area or allowed to spill outside it.
- Border, radius, and — for Normal and Hover states separately — a Transform popover (rotate, scale, offset, opacity), Box Shadow, and CSS Filters.
| Setting | What it does |
|---|---|
| **Overflow** | Whether hover transforms are clipped to the image area or allowed to spill outside it. Set to hidden for a contained zoom; visible lets an image grow past its frame. |
| **Border / Radius** | Standard border controls on the image itself. |
| **Transform** (Normal & Hover) | Rotate, scale, offset X/Y and opacity — a popover per state. |
| **Box Shadow** (Normal & Hover) | Separate shadows per state. |
| **CSS Filters** (Normal & Hover) | Blur, brightness, contrast, saturation and hue. |
Because Normal and Hover are configured separately, the transition between them is what creates the animation — set scale to 1 on Normal and 1.05 on Hover for a standard zoom-in.
## Content styling
- **Hide Product Count** — the product count badge is hidden by default; turn this off if you'd like the count shown.
- **Position** — Relative (sits naturally below the image) or Absolute (overlays directly on top of the image, positioned at the bottom).
- Font colour, background colour, an optional background blur effect (for a frosted-glass look behind overlaid text), padding, border, and box shadow.
![The Content styling section of the widget](../assets/img/woo-categories-transform-controls.png)
*Screenshot: the widget's Content styling section showing Hide Product Count, the Position selector, and the background blur control.*
| Setting | Default | What it does |
|---|---|---|
| **Hide Product Count** | On | The count badge is hidden by default. Switch this off to show it. |
| **Position** | Relative | **Relative** sits the text naturally below the image. **Absolute** overlays it on the image, anchored to the bottom. |
| **Font / Background colour** | — | Colours for the title text and the band behind it. |
| **Background blur** | — | Frosted-glass effect behind overlaid text. Most effective with a semi-transparent background colour. |
| **Padding / Border / Box shadow** | — | Standard spacing and framing for the text area. |
## Setting it up
1. Add the widget to your Shop page (or wherever your category tiles are displayed).
2. For an overlay-style card, set Content Position to Absolute and add a background colour with some transparency, or enable the blur effect for a frosted look.
3. Configure hover effects under Image styling for a polished interactive feel.
1. Add the widget to your Shop page, or wherever category tiles are displayed.
2. For an overlay card, set **Position** to Absolute and give the background a semi-transparent colour — then add blur for a frosted look.
3. Configure the Normal and Hover transforms under Image styling to create the hover animation.
4. Preview on the front end; the editor may not show real category tiles depending on how your shop page is configured.
## Good to know
- **Two things happen automatically once this plugin and WooCommerce are both active**: the tile markup restructuring (extra wrapper elements around each category tile) happens site-wide regardless of whether this widget is placed anywhere, but the actual **styling** only applies once you've placed the widget on the page showing those tiles.
- Styling isn't scoped to a single widget instance — placing the widget once styles every category tile shown on that page.
- The product count badge is **hidden by default** — if you expect to see a count and it's missing, check the "Hide Product Count" setting.
:::note Markup changes are store-wide; styling is not
Once this plugin and WooCommerce are both active, the **tile markup restructuring** (extra wrapper elements around each tile) happens site-wide whether or not you've placed this widget. The **styling** only applies on pages where the widget is present.
This split is intentional — it means the markup is consistent everywhere, so your CSS or a child theme can rely on it even on pages without the widget.
:::
- **Styling is not scoped per instance.** Placing the widget once styles every category tile on that page; adding a second instance won't give you two different looks on the same page.
- **The product count is hidden by default.** If you expected a count and it's missing, check **Hide Product Count** rather than assuming the theme removed it.

32
docs/dotjuice-elementor-tools/widgets/woo-my-account-transform.md
View File

@@ -1,23 +1,39 @@
# Woo My Account Transform
Bring WooCommerce's My Account area in line with the rest of your design.
Found in the Elementor panel under **Dotjuice → Woo My Account Transform**. Requires WooCommerce.
![The My Account area with custom button and link styling](../assets/img/woo-my-account-transform.png)
*Screenshot: a logged-in My Account page — Orders view — showing styled action buttons and order-table links matching the site's branding.*
## How it works
Place this widget on your My Account page template (typically inside your Elementor Theme Builder's My Account template). It detects buttons and links within the account content area and applies the styling you configure below.
Place this widget on your My Account page template, typically inside Elementor's Theme Builder My Account template. It detects the buttons and links within the account content area and applies your styling to them.
The My Account area is normally one of the hardest parts of a WooCommerce store to style, because it's rendered by WooCommerce templates rather than built in Elementor. This widget bridges that gap without you needing to override any templates.
## Styling
- **Button Style** — Normal and Hover states, each with text colour, background colour, border, border radius, and box shadow, plus shared typography and padding. Applies to account action buttons (e.g. form submit buttons, "Pay", "Cancel").
- **Link Style** — typography, plus Normal and Hover text colour, applied to order-table links: download links, product name links, and order number links.
| Section | Applies to | Controls |
|---|---|---|
| **Button Style** | Account action buttons — form submits, "Pay", "Cancel", "View order" | Normal and Hover states with text colour, background, border, radius and box shadow, plus shared typography and padding |
| **Link Style** | Order-table links — downloads, product names, order numbers | Typography, plus Normal and Hover text colour |
## Setting it up
1. Add the widget anywhere inside your My Account page template.
2. Configure your button and link colours to match your site's branding.
3. Visit the My Account page while logged in (as a real customer account, since this only applies within the actual account content) to check the styling.
1. Add the widget anywhere inside your My Account page template. Position doesn't matter — it styles the whole area, not the spot where it sits.
2. Set your button and link colours to match your branding.
3. **Preview on the front end while logged in as a real customer account.** This is the only reliable way to check it.
## Good to know
- **Styling applies across the whole My Account area on that page, not just near the widget** — you only need to place this widget once on your My Account template for it to take effect everywhere within it.
- You won't see live account content while editing in Elementor — the editor shows a placeholder instead, since there's no real logged-in account context inside the editor. Preview your changes by viewing the actual My Account page on the front end while logged in.
:::caution The editor can't show you real account content
Elementor has no logged-in customer context, so the editor shows a placeholder rather than live orders, addresses or downloads. Style with the front end open in another tab and refresh as you go.
A test customer account with at least one completed order gives you something realistic to style against — an empty account shows almost none of the elements these controls target.
:::
- **Styling applies across the whole My Account area on that page, not just near the widget.** Place it once per template; adding more instances does nothing extra.
- Buttons and links inside the account content are targeted, but the account **navigation menu** is a separate element — style that with Elementor's own controls or your theme.
- If your theme heavily overrides WooCommerce's account templates with custom markup, some elements may fall outside what this widget targets.

44
docs/dotjuice-elementor-tools/widgets/woo-page-numbers.md
View File

@@ -1,29 +1,51 @@
# Woo Page Numbers
Styleable product pagination that co-operates with AJAX filtering.
Found in the Elementor panel under **Dotjuice → Woo Page Numbers**. Requires WooCommerce.
![Styled product pagination on a shop archive](../assets/img/woo-page-numbers.png)
*Screenshot: a shop archive footer showing the pagination with the current page highlighted in the site's accent colour.*
## How it works
Place this widget on your Shop page or any product archive/category template, where it will show. It wraps WooCommerce's built-in pagination and applies the styling you configure.
Place this widget on your Shop page or any product archive or category template. It wraps WooCommerce's built-in pagination and applies your styling.
This widget only shows real pagination when there's more than one page of results to paginate through — on a page with too few products to need pagination, it will render an empty space.
It only renders real pagination when there is more than one page of results. On an archive with too few products to paginate, it renders empty space.
## Styling
There's no Content tab — every setting lives under Style:
This widget has no Content tab — everything lives under Style.
- **Alignment** — left, centre, or right.
- **Typography** — font styling shared across all pagination links.
- **Normal / Hover** — text and background colour for regular page number links.
- **Active** — text and background colour for the current page indicator (styled separately, since it's not a clickable link).
- **Border** and **Padding** — spacing and border styling for each page number.
| Setting | What it does |
|---|---|
| **Alignment** | Left, centre or right. |
| **Typography** | Shared across all pagination links. |
| **Normal / Hover** | Text and background colour for regular page-number links. |
| **Active** | Text and background colour for the current page. Styled separately because it isn't a clickable link. |
| **Border** | Border style, colour, width and radius per page number. |
| **Padding** | Space inside each page number, which controls the tap-target size. |
:::tip Mind the tap target on mobile
Padding here decides how big each number is to tap. Anything under about 44px square gets fiddly on a phone — worth checking at a mobile breakpoint before you ship.
:::
## Setting it up
1. Add the widget to your Shop page or a product category archive template.
2. Style the Normal, Hover, and Active states to match your site.
3. Preview on the live site with enough products to trigger real pagination — the Elementor editor shows a fixed example (pages 1–4) purely so you can preview your styling, which won't match your site's real page count.
2. Style the Normal, Hover and Active states so the current page is clearly distinct.
3. **Preview on the live site with enough products to trigger real pagination.** The editor shows a fixed 1–4 example purely so you have something to style against — it won't match your real page count.
## Works with the AJAX Product Filter
If a Pro [Woo Product Filter](../../dotjuice-elementor-tools-pro/widgets/woo-product-filter.md) is on the same page with AJAX enabled, clicking a page number loads that page's products in place — no full reload — while keeping the shopper's active filters applied.
The browser URL updates to the normal pretty archive form, e.g. `/t-shirts/page/2/`, so paged views stay shareable and bookmarkable and the back/forward buttons work as expected. On sites using plain permalinks it falls back to `?paged=2`.
No extra configuration is needed — place both widgets on the page and they find each other.
## Good to know
- **The Elementor editor always shows a sample 4-page pagination** so you have something to style against — this is a preview aid only, not a reflection of your real page count. Check the actual front end to see your real pagination.
- **The editor always shows a sample four-page pagination.** It's a styling aid, not a reflection of your catalogue. Always confirm on the front end.
- Because it wraps WooCommerce's native pagination, it respects your **Products per page** setting from WooCommerce and your theme — change the page count there, not here.
- On an archive with a single page of results the widget outputs nothing visible, which can leave a gap if you've given its container padding or a margin.

98
docs/dotjuice-elementor-tools/widgets/woo-products-transform.md
View File

@@ -1,90 +1,102 @@
# Woo Products Transform
Add hover effects, image rollovers and colour swatches to an Elementor Pro product grid.
Found in the Elementor panel under **Dotjuice → Woo Products Transform**. Requires WooCommerce and Elementor Pro's Products widget.
![A product grid with hover effects applied](../assets/img/woo-products-transform-frontend.png)
*Screenshot: a product grid on the shop page, one tile mid-hover showing its image scaled with the content overlay visible.*
## How it works
Drop this widget onto the same page or template as an Elementor Pro **Products** widget — your Shop archive, a product-category template, or any page showing a product loop. It restructures each product in that loop into styleable wrapper sections (an image wrapper and a content wrapper) and applies the effects you configure to **every product in the loop**: image hover effects, colour swatches, title/price tweaks, an optional image rollover, and overflow control.
Drop this widget onto the same page or template as an Elementor Pro **Products** widget — your Shop archive, a category template, or any page showing a product loop. It restructures each product into styleable wrapper sections (an image wrapper and a content wrapper) and applies your effects to **every product in that loop**.
It doesn't render a product grid of its own — it *transforms* the grid rendered by Elementor Pro's Products widget. So you always use the two together: the Products widget for the grid, this widget for the styling and behaviour.
**It does not render a grid of its own.** It transforms the grid rendered by Elementor Pro's Products widget, so the two are always used together: the Products widget for the grid, this one for styling and behaviour.
There's no Content tab — every setting lives under **Style**, grouped into the four sections below. Most settings preview live in the Elementor editor; hover-based effects (transforms, rollover, swatch image swaps) are best confirmed on the live front end.
There's no Content tab — everything lives under **Style**, in the four sections below. Most settings preview live in the editor; hover-based effects are best confirmed on the front end.
![The Woo Products Transform style sections](../assets/img/woo-products-transform-controls.png)
*Screenshot: the widget selected in the editor with the **Image transform** section open, showing the Normal/Hover tabs and the transform popover.*
## Image transform
Controls the product image and its hover behaviour.
| Setting | What it does |
|---|---|
| **Disable Default Add to Cart** | Removes WooCommerce's default loop "Add to cart" button (useful if you add your own, or want a cleaner grid). |
| **Overflow** | `overflow` for the image wrapper — set to **Hidden** to clip a scaled/zoomed image to its frame. |
| **Border** (Style / Colour / Width / Radius) | A border around the product image, with rounded-corner control. |
| **Disable Default Add to Cart** | Removes WooCommerce's loop "Add to cart" button — useful for a cleaner grid, or if you add your own. |
| **Overflow** | Overflow for the image wrapper. Set **Hidden** to clip a scaled image to its frame. |
| **Border** (style, colour, width, radius) | A border around the product image. |
Below those, **Normal** and **Hover** tabs each expose the same image effects, so you can animate between a resting state and a hover state:
Below those, **Normal** and **Hover** tabs expose the same set of effects, so you animate between a resting state and a hover state:
- **Transform** — a popover with **Rotate**, **Scale**, and **Offset X/Y**. Set a subtle scale/offset on Hover for a zoom-on-hover effect.
- **Opacity** — fade the image (e.g. dim on hover, or fade in).
- **Transform** — a popover with Rotate, Scale and Offset X/Y. A subtle scale on Hover gives the standard zoom.
- **Opacity** — fade the image in or out.
- **CSS Filters** — blur, brightness, contrast, saturation, hue.
- **Box Shadow** — a shadow on the image.
- **Box Shadow** — per state.
At the very top of this section is the **Enable Image Rollover** toggle (Pro) — see [Image Rollover](#image-rollover-pro) below. When rollover is on, the transform/opacity/filter/shadow controls above are hidden and disabled, because rollover and those hover effects are mutually exclusive.
At the top of this section sits **Enable Image Rollover** (Pro). Switching it on **hides and disables** the transform, opacity, filter and shadow controls above, because rollover and hover transforms are mutually exclusive — you can't scale an image and swap it for another at the same time.
## Image Rollover (Pro)
Instead of transforming the product image on hover, show a **second image** — ideal for the same garment on a different model, or a front/back view.
Instead of transforming the image on hover, show a **second image** — the same garment on a different model, or a front/back view.
Turn on **Enable Image Rollover** (top of the Image transform section) to switch the widget into rollover mode. The featured image crossfades out as the second image crossfades in.
![A product tile mid-rollover showing the second image](../assets/img/woo-products-transform-rollover.png)
*Screenshot: two product tiles side by side, one at rest showing the featured image and one hovered showing its rollover image.*
**Where the second image comes from**, per product, in priority order:
**Where the second image comes from,** per product, in priority order:
1. A dedicated **Rollover Image** — set it on the product edit screen (Product → **Rollover Image (Hover)** box in the sidebar).
1. A dedicated **Rollover Image**, set on the product edit screen in the **Rollover Image (Hover)** box.
2. Otherwise the product's **first gallery image**, used automatically as a fallback.
You can tick **Disable rollover for this product** on any product to opt it out entirely.
**Rollover controls** (shown once rollover is on):
Tick **Disable rollover for this product** on any product to opt it out.
| Setting | What it does |
|---|---|
| **Effect** | How the second image enters: Fade, Zoom In/Out, or Slide Up/Down/Left/Right. |
| **Duration (ms)** | How long the crossfade/slide takes. |
| **Easing** | The transition curve — Ease, Linear, the Ins/Outs, plus Smooth and Back / Overshoot. |
| **Disable Gallery Fallback** | Only roll over products that have an explicit Rollover Image. Products relying on the gallery fallback keep their featured image untouched. |
| **Effect** | How the second image enters — Fade, Zoom In/Out, or Slide Up/Down/Left/Right. |
| **Duration (ms)** | Length of the crossfade or slide. |
| **Easing** | The transition curve — Ease, Linear, the Ins/Outs, plus Smooth and Back/Overshoot. |
| **Disable Gallery Fallback** | Only roll over products with an explicit Rollover Image. Products relying on the gallery keep their featured image untouched. |
Second images use native lazy loading, and on touch devices (no hover) products simply show their featured image.
Second images use native lazy loading. On touch devices, where there's no hover, products simply show their featured image.
## Variation swatches (Pro)
For **variable** products, show clickable colour swatches under each product in the loop. Clicking a swatch swaps the product image to that variation's image — shoppers preview colours without opening the product. These controls only appear when Dotjuice Elementor Tools **Pro** is active.
For **variable** products, show clickable colour swatches beneath each product in the loop. Clicking one swaps the product image to that variation's image, letting shoppers preview colours without opening the product.
- **Show colour swatches** — the master toggle (off by default).
- **Swatch taxonomy** — which product attribute drives the swatches (e.g. `Colour` / `pa_color`). Swatch colours come from the attribute term's colour (see the WooCommerce Hacks attribute colour manager).
- **Swatch Gap** and **Alignment** — spacing and horizontal alignment of the swatch row.
- **Normal / Hover / Active** tabs — **Swatch Size**, **Border**, and **Border Radius** for each state (Active = the currently selected swatch).
| Setting | What it does |
|---|---|
| **Show colour swatches** | Master toggle, off by default. |
| **Swatch taxonomy** | Which attribute drives the swatches, e.g. `Colour` / `pa_color`. |
| **Swatch Gap / Alignment** | Spacing and horizontal alignment of the swatch row. |
| **Normal / Hover / Active** | Swatch Size, Border and Border Radius per state. Active is the currently selected swatch. |
Swatch colours come from the attribute term colours you set under [Product Attribute Colours](../product-attribute-colours.md).
## Content transform
Styles the block holding the product title and price, and offers a few content tweaks.
Styles the block holding the title and price, plus a few content tweaks.
- **Change title tag** — output the product title as **H2–H6** instead of the default (a second dropdown, **Title heading tag**, appears when this is on).
- **Hide Star Ratings** / **Hide Prices** — remove those elements from the loop.
- **Content wrapper styling** — **Background Colour**, **Blur** (a backdrop-blur behind the content, e.g. for an overlay over the image), **Padding**, **Border** (Style / Colour / Width / Radius), and **Box Shadow**.
| Setting | What it does |
|---|---|
| **Change title tag** | Output the product title as H2–H6 instead of the default. A **Title heading tag** dropdown appears when on. |
| **Hide Star Ratings** / **Hide Prices** | Remove those elements from the loop. |
| **Content wrapper styling** | Background colour, **Blur** (backdrop blur, for an overlay sitting over the image), padding, border and box shadow. |
## Box Transform
- **Show Overlay** — the `overflow` of each product tile (`li.product`). Set to **Hidden** to clip child content (like a scaled image or an absolutely-positioned content overlay) to the tile.
**Show Overlay** sets the overflow of each product tile. Set it to Hidden to clip child content — a scaled image, or an absolutely-positioned content overlay — to the tile boundary.
## Setting it up
1. Add the widget to the same template/page as your Elementor Pro Products widget.
2. Decide between hover **image transforms** and **Image Rollover** (Pro) — you can only use one at a time.
3. If using transforms, set a resting state on the **Normal** tab and the effect on **Hover**.
4. If using rollover, set a **Rollover Image** on the products that need one (or rely on the gallery fallback), then pick an Effect, Duration and Easing.
1. Add the widget to the same template or page as your Elementor Pro Products widget.
2. Choose between hover **image transforms** and **Image Rollover** — you can only use one.
3. For transforms: set the resting state on **Normal**, the effect on **Hover**.
4. For rollover: set a Rollover Image on the products that need one (or rely on the gallery fallback), then pick Effect, Duration and Easing.
5. For variable products, enable **Show colour swatches** and pick the driving attribute.
6. Use **Content transform** for the title tag and to hide price/rating, and **Box Transform** to clip overflow.
6. Use **Content transform** for the title tag and to hide price or rating, and **Box Transform** to clip overflow.
## Good to know
- Rollover, swatches and the transform effects all keep working on products loaded by the Dotjuice AJAX product filter.
- The **Image Rollover** and **Variation swatches** controls only appear when Dotjuice Elementor Tools **Pro** is active — deactivating Pro removes those features (and shows a short "available in Pro" note); the rest of the widget keeps working.
- Because the widget restyles Elementor Pro's Products loop, it only has a visible effect on pages that actually render that loop.
- **It only has a visible effect on pages that actually render an Elementor Pro Products loop.** On a page without one, the widget does nothing.
- **Rollover, swatches and transforms all keep working on products loaded by the Dotjuice AJAX product filter**, so filtered results behave identically to the first page load.
- **The Pro-only controls disappear when Pro is deactivated**, replaced by a short "available in Pro" note. The rest of the widget carries on working.
- Set **Overflow** to Hidden before spending time on a scale effect — without it, a scaled image spills over neighbouring tiles and the grid looks broken.

77
docs/dotjuice-elementor-tools/widgets/woo-taxonomy-list.md
View File

@@ -1,61 +1,90 @@
# Woo Taxonomy List
Cascading term lists from any taxonomy — a "Shop by Category" block, or a plain list of blog categories.
Found in the Elementor panel under **Dotjuice → Woo Taxonomy List**.
**Note:** despite the "Woo" name, this widget works with any public taxonomy on your site — product categories, blog categories, tags, or a custom taxonomy — not just WooCommerce. It currently only appears in the widgets panel when WooCommerce is active; if you'd like to use it purely for blog categories on a site without WooCommerce, get in touch with support.
![A grouped category list on the front end](../assets/img/woo-taxonomy-list-frontend.png)
*Screenshot: a sidebar "Shop by Category" block showing two parent terms as headings with their child terms listed and counts in brackets.*
:::note Not just for WooCommerce
Despite the name, this widget works with **any public taxonomy** — product categories, blog categories, tags, or a custom taxonomy. It only appears in the widgets panel when WooCommerce is active, so on a site without WooCommerce it isn't available even for blog categories. Get in touch with support if you need it standalone.
:::
## Two display modes
**Flat mode** lists every term in the chosen taxonomy in one simple list — good for a straightforward "browse all categories" block.
**Hierarchical mode** (the default) lets you pick specific parent terms and shows each with its children nested beneath — a "Shop by Category" block grouping related subcategories under their parent.
**Hierarchical mode** (the default) lets you choose specific parent terms, and displays each one with its child terms nested beneath — good for a "Shop by Category" style block where you want to group related subcategories under their parent.
**Flat mode** lists every term in the taxonomy in one simple list — a straightforward "browse all categories" block.
## Content settings — Widget Heading
| Setting | What it does |
|---|---|
| **Heading Text** | An optional title shown above the list. |
| **Heading URL** | If set (and Heading Text is filled in), makes the heading a clickable link. |
| **Heading Tag** | The HTML tag used for the heading (H2–H6, or a plain div), for correct document structure. |
| **Heading Text** | Optional title above the list. |
| **Heading URL** | Makes the heading a link. Only applies when Heading Text is filled in. |
| **Heading Tag** | H2–H6 or a plain div, so the page keeps a sensible document outline. |
## Content settings — List Settings
![The List Settings section with the taxonomy and parent term pickers](../assets/img/woo-taxonomy-list-controls.png)
*Screenshot: the widget's **List Settings** section showing the Taxonomy dropdown, the Parent Terms multi-select populated with terms, and the Max Depth control.*
| Setting | Default | What it does |
|---|---|---|
| **Taxonomy** | Product categories | Which taxonomy to pull terms from — every public taxonomy registered on your site is available here. |
| **Show All Terms (Flat)** | Off | Switches to flat mode (see above). |
| **Parent Terms** | — | Hierarchical mode only. Choose which parent term(s) to display, each with its children listed beneath. |
| **Show Parent Term** | On | Hierarchical mode only. Shows the parent term itself as a clickable heading above its children. |
| **Max Depth** | 1 level | Hierarchical mode only. How many levels of nested children to show beneath each parent — 1, 2, 3, or all levels. |
| **Hide Empty Terms** | On | Excludes terms with no posts or products assigned to them. |
| **Order By** | Name | Name, Count, Slug, or Term ID. |
| **Taxonomy** | Product categories | Which taxonomy to pull terms from. Every public taxonomy on your site is listed. |
| **Show All Terms (Flat)** | Off | Switches to flat mode. |
| **Parent Terms** | — | Hierarchical only. Which parent term(s) to display, each with its children beneath. |
| **Show Parent Term** | On | Hierarchical only. Shows the parent itself as a clickable heading above its children. |
| **Max Depth** | 1 level | Hierarchical only. How many levels of children to show — 1, 2, 3, or all. |
| **Hide Empty Terms** | On | Excludes terms with nothing assigned to them. |
| **Order By** | Name | Name, Count, Slug or Term ID. |
| **Order** | Ascending | Ascending or descending. |
:::tip The Parent Terms list follows the Taxonomy dropdown
Change **Taxonomy** and the **Parent Terms** picker repopulates with terms from the new taxonomy. This cascade only runs inside the Elementor editor — so if you're scripting or importing widget settings, set both fields explicitly rather than expecting the cascade to fill one in.
:::
## Content settings — Display
| Setting | What it does |
|---|---|
| **Show Term Count** | Adds a post/product count in brackets after each term name. |
| **List Icon** | An optional icon (as a CSS icon class, e.g. from Font Awesome) shown before each term link. |
| **Show Term Count** | Adds the post or product count in brackets after each term. |
| **List Icon** | An optional icon before each term link, given as a CSS icon class (e.g. Font Awesome). |
## Styling
Extensive styling is available, organised into: **Heading** (typography, colour, spacing), **List Container** (padding, background, border, shadow), **Parent Items** and **Parent Link Text** (hierarchical mode only), **List Items** (marker style — none, disc, circle, square, numbers, or letters — spacing, indentation, background, and hover background), **Link Text** (typography, colour, hover underline), and **List Icon** (size, colour, spacing) if you've set one.
Grouped into sections:
| Section | Covers |
|---|---|
| **Heading** | Typography, colour, spacing |
| **List Container** | Padding, background, border, shadow |
| **Parent Items** / **Parent Link Text** | Hierarchical mode only — the parent row and its link text |
| **List Items** | Marker style (none, disc, circle, square, numbers, letters), spacing, indentation, background, hover background |
| **Link Text** | Typography, colour, hover underline |
| **List Icon** | Size, colour, spacing — only relevant if you've set an icon |
## Setting it up
**For a flat list** (e.g. "all blog categories"):
1. Choose your Taxonomy.
**A flat list**, e.g. all blog categories:
1. Choose your **Taxonomy**.
2. Turn on **Show All Terms (Flat)**.
3. Style as needed.
**For a grouped list** (e.g. "Shop by Category" with subcategories):
1. Choose your Taxonomy.
2. Leave Flat mode off, and select your parent term(s) in **Parent Terms**.
3. Set **Max Depth** to however many levels of children you want shown.
**A grouped list**, e.g. "Shop by Category" with subcategories:
1. Choose your **Taxonomy**.
2. Leave flat mode off and select your **Parent Terms**.
3. Set **Max Depth** to how many levels of children you want.
4. Style as needed.
## Good to know
- **If your configuration doesn't resolve to any terms** (for example, hierarchical mode with no parent terms selected yet), the widget shows a helpful explanatory message while you're editing in Elementor — but shows nothing at all on the live front end. Always double-check your configuration is complete before publishing.
- The **Parent Terms** picker updates automatically to show terms from whichever taxonomy you've selected, but this live update only works while you're inside the Elementor editor.
:::caution An incomplete configuration renders nothing on the front end
If your settings don't resolve to any terms — hierarchical mode with no parent terms selected yet is the usual case — the editor shows an explanatory message, but the live site shows **nothing at all**. Confirm the configuration is complete before publishing.
:::
- **Hide Empty Terms is on by default.** A term you expect to see but which has no products assigned won't appear; switch it off if you're building the catalogue out of order.
- Ordering applies within each level, so under a parent the children sort independently of how the parents themselves are ordered.