README

mhinspeya/inspeya-hyva-popup

Main Functionalities
Installation
Configuration
Popup Rules & Targeting
Popup Positioning
Specifications
Attributes
Exception Handling & Logging
PHP Compatibility

Main Functionalities

The MHinspeya Hyvä Popup Module allows Magento 2 store owners and marketers to create dynamic, targeted, responsive, and fully customisable popup messages directly from the Magento admin panel.

This module is highly flexible and supports:

✔ Custom Popup Creation

Create multiple popups from the backend
Add HTML content, images, text, promotions, newsletter forms, etc.
Full support for Hyvä theme and Alpine.js
Easy-to-use admin UI for popup design

✔ Powerful Popup Display Rules

Customer Group targeting
Specific Page targeting
Display only during Valid From and Valid To date ranges
Enable or disable each popup individually
Show to guests, logged-in users, or specific customer groups

✔ Popup Type Support

The module delivers popups for the following page contexts:

Popup Type	AJAX Endpoint	Description
Homepage	`GetPopups`	General sitewide / homepage popups
Category	`CategoryPopups`	Targeted to specific category IDs
Product	`ProductsPopups`	Triggered on product detail pages
CMS Page	`CmsPopups`	Targeted to specific CMS page identifiers
Cart	`CartPopups`	Shown on cart page; includes cart total and free-shipping rule support

⚠️ Checkout is not supported. No popup is displayed on the checkout page.

✔ Popup Position Control

Choose where the popup appears on the screen:

Center
Top
Bottom
Left
Right
Floating corners
Full-width banners

✔ Display Frequency Control

Control how often a popup is shown per visitor:

Every time
Once per hour
Once per day
Once per week
Once per month

Frequency is tracked per customer (by user ID for logged-in, by IP for guests) per store.

✔ Cart & Free Shipping Rule Integration

The cart popup type supports:

Cart total and item count awareness
Free shipping cart price rule integration (rule conditions are passed to the frontend)
Show/hide based on cart empty state
FOMO (Fear Of Missing Out) messaging support

✔ Stock Feed Display

The product popup type supports:

Real-time stock quantity from MSI (Multi-Source Inventory)
Configurable product child SKU stock aggregation
stock_max_num threshold for low-stock urgency messaging

✔ Fully Responsive

The popup adapts to:

Desktop
Tablet
Mobile

No layout breaking — optimised for all Hyvä viewports.

Installation

* For production environments, use --keep-generated.

Type 1: Manual (Zip) Installation

Extract the module to:
```
app/code/MHinspeya/Popup
```

Enable the module:

php bin/magento module:enable MHinspeya_Popup

Run setup upgrade:
```
php bin/magento setup:upgrade
```
Compile DI:
```
php bin/magento setup:di:compile
```
Clear cache:
```
php bin/magento cache:flush
```

Type 2: Composer Installation

Add repository if needed:

composer config repositories.inspeya composer https://repo.inspeya.com/

Install the module:

composer require mhinspeya/inspeya-hyva-popup

Enable module:

php bin/magento module:enable MHinspeya_Popup

Run upgrade:
```
php bin/magento setup:upgrade
```
Compile DI:
```
php bin/magento setup:di:compile
```
Clear cache:
```
php bin/magento cache:flush
```

Configuration

Admin Path:

Stores → Configuration → MHinspeya → Popup Settings

Here you can:

Globally enable / disable popup functionality
Enable or disable popup per page type (Homepage, Category, Product, CMS, Cart)
Configure front-end behaviour & loading logic
Set default animations
Manage overlay settings
Enter and validate the module license key

Individual popups are managed under:

Marketing → Popup Manager

Each popup contains:

Field	Description
Title	Internal name for the popup
Content	HTML / Images / Text body
Customer Group	Who to show this popup to
Display	Which page type(s) to show on
Store	Which store views to target
Valid From / Valid To	Date range the popup is active
Priority Order	Higher value = shown first
Display Frequency	How often to show per visitor
Display on Device	Desktop / Mobile / Both
Popup Position	Where on screen to render
Popup Width / Height	Dimensions
When to Show	Immediately / After delay / On scroll
Hide After (seconds)	Auto-dismiss timer
Status	Active / Inactive

Popup Rules & Targeting

✔ Customer Group Based Targeting

Display popup only to:

Guests
Logged-in customers
Specific customer groups

✔ Page-Level Targeting

Choose where the popup appears:

Homepage
Category page
Product page
CMS page
Cart page

Note: The popup module does not target the checkout page. No popup endpoints exist for checkout.

✔ Date Range Control

Every popup supports:

Valid From (start date)
Valid To (end date)

Popups only display during the configured date range. Dates are stored in DD.MM.YYYY format and compared server-side using MySQL STR_TO_DATE.

✔ Store View Control

Each popup can be scoped to one or more store views using the store_id multi-select field.

Popup Positioning

Available positions:

Center modal
Top bar
Bottom bar
Left sidebar
Right sidebar
Top-left
Top-right
Bottom-left
Bottom-right
Full width

100% responsive on all screen sizes.

Exception Handling & Logging

All controllers implement structured exception handling:

Admin controllers (Save, MassDelete, AddRow): catch LocalizedException first for user-friendly messages, then \Exception for unexpected errors — all logged to var/log/popup.log.
AJAX controllers (GetPopups, CartPopups, CategoryPopups, CmsPopups, ProductsPopups): the entire execute() method is wrapped in try/catch. Any error returns a safe JSON response {"error": true} instead of a 500 page crash.
Helper (Helper/Data): getCartPriceRuleByID() is guarded — a missing rule ID returns [] and logs a warning.

Log file: var/log/popup.log

All services are injected via Dependency Injection — no ObjectManager::getInstance() usage exists in this module.

PHP Compatibility

PHP Version	Status
PHP 8.0	✅ Compatible
PHP 8.1	✅ Compatible
PHP 8.2	✅ Compatible
PHP 8.3	✅ Compatible
PHP 8.4	✅ Compatible

No removed PHP 8.0 functions used
No ${var} deprecated string interpolation
No implicit nullable parameters
strtotime() calls are guarded against null values on all AJAX controllers
All class properties are explicitly declared (no dynamic properties)

Specifications

Feature	Supported
Hyvä Compatibility	✔
Alpine.js Integration	✔
Custom Popup Builder	✔
Customer Group Targeting	✔
Page-level Targeting (excl. Checkout)	✔
Valid From / To Date Range	✔
Display Frequency Control	✔
Multi-position Popups	✔
Cart & Free Shipping Rule Support	✔
MSI Stock Feed Display	✔
Fully Responsive	✔
Unlimited Popups	✔
Overlay & Animations	✔
Structured Exception Handling	✔
Dedicated Log File	✔
PHP 8.0–8.4 Compatible	✔
Magento 2.4.x Compatible	✔

Attributes

This module does not create product or category attributes.

It includes:

Admin popup grid (Marketing → Popup Manager)
Popup creation / edit form
Popup rule & frequency engine
Frontend Hyvä popup renderer (Alpine.js)
Custom logger (var/log/popup.log)
License key validation observer

mhinspeya / inspeya-hyva-popup

Maintainers

Package info

Statistics

Security