# Woo Product Collections Widget

> Renders a single WooCommerce collection — pick a category, tag, or attribute term, and the widget builds a hero banner linking to that term's archive.

**Class file:** `includes/Elements/Woo_Collections.php` (670 lines)
**Slug:** `woo-collections` (widget id `eael-woo-collections`)
**Public docs:** <https://essential-addons.com/elementor/docs/woo-product-collections/>
**Pro-shared:** Pro-only. **Requires WooCommerce active.**

## Overview

Single-collection hero widget — picks one taxonomy term (product category / tag / attribute) and renders a styled banner card with term image, name, product count, and link. Smallest of the WooCommerce-Pro widgets (670 lines). Uses Pro's own `Helper` (not Lite's). Inline `apply_filters('eael/is_plugin_active', ...)` guard to show an admin notice when WooCommerce is missing.

## Pro vs Lite

Pro-only.

## File Map

| File | Role |
| --- | --- |
| `includes/Elements/Woo_Collections.php` | Widget class (670 lines) — no template files |
| `src/css/view/woo-collections.scss` → `assets/front-end/css/view/woo-collections.min.css` | Banner styling |
| `config.php` entry `'woo-collections'` | Self CSS only (no JS) |

No frontend JS. No template directory — rendering is inline in `render()`.

## Architecture

- **WooCommerce gate via filter** — `apply_filters('eael/is_plugin_active', 'woocommerce/woocommerce.php')` at line 78. When WooCommerce is missing, a `RAW_HTML` control renders a warning instructing the user to install WC. The widget loads, but functions only when WC is active.
- **Two collection types** — `category` / `tags` / `attributes`. Each maps to a WordPress taxonomy via `Helper::get_terms_list('product_cat')` (line 110) / `product_tag` / `pa_*` attributes.
- **Categories use Pro's own `Helper`** (line 10), not Lite's — atypical. Pro's Helper has `get_terms_list` which Lite's doesn't.
- **`has_widget_inner_wrapper` opt-out** — same pattern as Advanced_Menu.
- **`get_categories()` returns 2 categories** — `'essential-addons-elementor'` AND `'woocommerce-elements'`. This is the WC-elements categorisation pattern; widget appears in both EA and WC widget groups in the editor.
- **No JS** — pure server-rendered HTML.

## Render Output

```html
<div class="eael-woo-collections eael-woo-collections-{element-id}">
  <a href="{term-archive-url}" class="eael-woo-collections-link">
    <div class="eael-woo-collections-image">
      [?] <img src="{term-image}" alt="{term-name}" />
    </div>
    <div class="eael-woo-collections-content">
      <h2 class="eael-woo-collections-title">{term-name}</h2>
      [?] <span class="eael-woo-collections-count">{product-count} products</span>
      [?] <span class="eael-woo-collections-button">{button-text}</span>
    </div>
  </a>
</div>
```

## Controls Reference

| Control id | Tab → Section | Type | Purpose |
| --- | --- | --- | --- |
| `eael_woo_collections_type` | Content → General | SELECT | `category` / `tags` / `attributes` |
| `eael_woo_collections_category` | Content → General | SELECT | Term ID (when type = category) |
| Tag / attribute selector | Content → General | SELECT | Per-type term picker |
| Show image / count / button | Content → Display | SWITCHER | Per-element visibility |
| Button text | Content → Display | TEXT | CTA label |
| Image / title / button / count styling | Style → ... | various | Per-region styling |

## Conditional Dependencies

```text
eael_woo_collections_type = 'category'  → category dropdown
eael_woo_collections_type = 'tags'      → tag dropdown
eael_woo_collections_type = 'attributes' → attribute dropdown

WooCommerce missing → only warning RAW_HTML renders
```

## JavaScript Lifecycle

N/A — pure CSS widget.

## Hooks & Filters

### Pro / EA hooks consumed

| Hook | Where | Purpose |
| --- | --- | --- |
| `eael/is_plugin_active` | line 78 | WC presence gate (Lite-owned filter) |

### Pro / EA hooks emitted

None.

## Common Issues

| Symptom | Likely cause | Diagnose | Fix |
| --- | --- | --- | --- |
| Warning notice in editor | WooCommerce not active | Verify WC plugin status | Activate WooCommerce |
| Empty banner | Term has no products / no image | Inspect term — `get_term( $id )` | Set term image; assign products to the term |
| Wrong term shown | Term ID outdated after import | Re-pick the term | Term picker dropdown |
| Count shows 0 | Product hidden via stock / visibility | Inspect term's product count | Adjust product visibility |

## Known Limitations

- **Single term per widget** — no multi-collection grid layout. For multi, drop multiple widget instances.
- **No fallback image** when term has no image — banner area renders blank
- **Image is term-image only** — can't use Featured Product image of the most-recent product
- **`get_categories()` returns 2 groups** — widget shows twice in Elementor's widget panel (under both EA Pro and WC categories). Intentional.
- **No `class_exists('WooCommerce')` direct check** — relies on `eael/is_plugin_active` filter, which Lite owns

## Cross-References

- Sibling: [`woo-product-slider.md`](woo-product-slider.md), [`woo-cross-sells.md`](woo-cross-sells.md)
- Shared patterns: [`_patterns.md`](_patterns.md)