# Interactive Promo Widget

> Single promotional banner with hover effect — image / video / SVG background with overlaid text. Optional Magnific Popup lightbox click-through.

**Class file:** `includes/Elements/Interactive_Promo.php` (355 lines)
**Slug:** `interactive-promo` (widget id `eael-interactive-promo`)
**Public docs:** <https://essential-addons.com/elementor/docs/interactive-promo/>
**Pro-shared:** Pro-only. Vendor: Magnific Popup (from Lite).

## Overview

Single promotional card — image + text overlay + call-to-action. Hover animation reveals additional content / button. Optional click-through opens Magnific Popup lightbox with embedded image / video / iframe. Smaller widget (355 lines) — minimal config.

## Pro vs Lite

Pro-only widget. Magnific Popup vendor from Lite.

## File Map

| File | Role |
| --- | --- |
| `includes/Elements/Interactive_Promo.php` | Widget class (355 lines) |
| `src/css/view/interactive-promo.scss` → `assets/front-end/css/view/interactive-promo.min.css` | Card + hover styling |
| `src/js/view/interactive-promo.js` (if present) → `.min.js` | Magnific Popup init |
| `EAEL_PLUGIN_PATH/assets/front-end/css/lib-view/magnific-popup/magnific-popup.min.css` | Lite — Magnific CSS |
| `EAEL_PLUGIN_PATH/assets/front-end/js/lib-view/magnific-popup/magnific-popup.min.js` | Lite — Magnific JS |
| `config.php` entry `'interactive-promo'` | Lite Magnific + Pro CSS |

## Architecture

- **Composes Lite's `Helper`** (line 12).
- **Magnific Popup from Lite** — for the optional lightbox click-through. Pro depends on Lite for the vendor.
- **Single-card widget** — no Repeater; one promo block per widget instance. Multi-promo layouts require multiple widget instances.
- **355 lines** — modest size; most are per-region style controls.

## Render Output

```html
<div class="eael-interactive-promo">
  <div class="eael-promo-bg">
    <img src="{image}" />
  </div>
  <div class="eael-promo-content">
    [?] <h3>{title}</h3>
    [?] <p>{description}</p>
    [?] <a class="eael-promo-button [eael-magnific-trigger]"
           href="{button_url}"
           [?] data-magnific="{image-or-video-url}">
      {button_text}
    </a>
  </div>
</div>
```

## Controls Reference

| Control id | Tab → Section | Type | Purpose |
| --- | --- | --- | --- |
| Background image | Content → Image | MEDIA | Card background |
| Title / description | Content → Text | TEXT / TEXTAREA | Overlay text |
| Button (label / url / magnific) | Content → Button | TEXT / URL / SWITCHER | CTA |
| Hover animation type | Content → Animation | SELECT | Zoom / fade / slide |
| Magnific lightbox enable | Content → Lightbox | SWITCHER | Open URL in Magnific Popup |

## Conditional Dependencies

```text
magnific_enable = 'yes' → data-magnific attribute set; lightbox triggers
button_show = 'yes' → button styling visible
```

## JavaScript Lifecycle

If Magnific enabled, JS binds click to open lightbox:

```js
$( '.eael-magnific-trigger' ).magnificPopup( { type: 'image' } );
```

## Hooks & Filters

Standard.

## Common Issues

| Symptom | Cause | Fix |
| --- | --- | --- |
| Lightbox doesn't open | Magnific Popup not loaded (Lite deactivated) | Activate Lite |
| Hover effect doesn't trigger | CSS animation class missing | Verify Pro CSS loaded |
| Content overflows on mobile | No responsive overrides | Use Pro responsive controls |

## Known Limitations

- **Single promo per widget** — no Repeater for multi-card layouts
- **Magnific Popup unmaintained upstream**
- **Magnific from Lite** — coupling
- **No `prefers-reduced-motion`** for hover animations

## Cross-References

- Sibling: [`interactive-cards.md`](interactive-cards.md), [`lightbox.md`](lightbox.md)
- Shared patterns: [`_patterns.md`](_patterns.md)