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:

⚠️ 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

1. Extract the module to:

   app/code/MHinspeya/Popup
   

2. Enable the module:

   php bin/magento module:enable MHinspeya_Popup
   

3. Run setup upgrade:

   php bin/magento setup:upgrade
   

4. Compile DI:

   php bin/magento setup:di:compile
   

5. Clear cache:

   php bin/magento cache:flush
   

Type 2: Composer Installation

1. Add repository if needed:

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

2. Install the module:

   composer require mhinspeya/inspeya-hyva-popup
   

3. Enable module:

   php bin/magento module:enable MHinspeya_Popup
   

4. Run upgrade:

   php bin/magento setup:upgrade
   

5. Compile DI:

   php bin/magento setup:di:compile
   

6. 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:

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

• 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

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 — All Rights Reserved