README

Panth Smart Badge adds product badges (labels such as "SALE", "NEW", "HOT" or a custom text or image) to product images on category listings, product detail pages and product sliders. Badges come from three sources: a "Product Badge" attribute set on the product, badge rules created in the admin (with product and category targeting, smart conditions and a schedule), and automatic detection of discounted, new and low-stock products. The module does not change how products are saved or priced; it only adds a badge layer on top of the product image on the storefront.

The storefront part is a small script that finds product images on the page, requests the badges for all products on the page from a module endpoint in one batched request and inserts them. Its selectors cover Hyva product cards and galleries as well as Luma product lists and the Fotorama gallery, so it works with both theme families. It is used by store owners who want to highlight products without editing each product manually.

Product page: kishansavaliya.com/magento-2-smart-badge.html

Features

Badge rules managed in an admin grid ("Manage Badges") with inline editing, mass delete and mass status change.
Eight preset badge types: "New", "Sale", "Hot", "Limited", "Bestseller", "Trending", "Exclusive" and "Featured", each with a default text, icon and colour.
Per-rule design: custom text, hex background colour, FontAwesome icon (about 60 icons offered), CSS animation (25 options) and advanced styling (border radius, font size, font weight, padding, opacity, box shadow, border width, style and colour).
Custom badge image upload (JPG, JPEG, PNG, GIF, WebP; maximum 2 MB; the file content must be one of these image types) stored under pub/media/smartbadge/.
Rule targeting by product IDs and category IDs (including products in child categories), with product and category choosers in the form.
Rule scope by store view and customer group.
Smart conditions combined with AND logic: price range, stock level, discount percentage, product age in days, stock status, customer rating and sales count.
Optional start and end date per rule; the schedule is checked on every request using the store timezone.
Display location per rule ("All Pages", "Product Detail Page Only", "Category Page Only", "Sliders Only") and a badge position that can be the same everywhere or set separately for category pages, product pages and sliders.
Three product attributes ("Product Badge", "Custom Badge Text", "Custom Badge Color") for setting a badge manually on a single product.
Automatic badges without any rule: a discount badge showing the percentage off when a special price is lower than the regular price, a "NEW" badge for products created in the last 30 days and an "Only N left" badge when the stock quantity is between 1 and 10.
Global settings for the maximum number of badges per product, how badge sources are combined, and how several badges are laid out on one image.
FontAwesome 6.5.1 Free (CSS, webfonts and license) bundled in the module under view/base/web/fontawesome/; no CDN request is made by this module.

Compatibility

Platform	Versions
Magento Open Source	2.4.4 to 2.4.8
Adobe Commerce	2.4.4 to 2.4.8
PHP	8.1, 8.2, 8.3, 8.4
Themes	Hyva and Luma

Composer constraints from composer.json: magento/framework ^103.0, magento/module-catalog ^104.0, magento/module-catalog-inventory ^100.4, magento/module-customer ^103.0, magento/module-review ^100.4, magento/module-backend ^102.0, magento/module-store ^101.1, magento/module-eav ^102.1, magento/module-ui ^101.2, magento/module-sales ^103.0, magento/module-wishlist ^101.2, magento/module-media-storage ^100.4, magento/module-config ^101.2.

Requirements

Magento Open Source or Adobe Commerce 2.4.4 to 2.4.8
PHP ~8.1.0 || ~8.2.0 || ~8.3.0 || ~8.4.0
mage2kishan/module-core ^1.0.17 (module Panth_Core); it provides the "Panth Extensions" admin menu, the theme configuration view model and the upload extension policy used by this module

Installation

composer require mage2kishan/module-smart-badge
bin/magento module:enable Panth_Core Panth_SmartBadge
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento setup:static-content:deploy -f
bin/magento cache:flush

setup:di:compile is only needed in production mode. setup:upgrade creates the two database tables, adds the three product attributes and runs the schema patches. When upgrading from 1.0.x it adds the store_ids and customer_group_ids columns; existing rules keep applying to all store views and all customer groups.

Check the module status:

bin/magento module:status Panth_SmartBadge

Configuration

Admin path: Stores > Configuration > Panth Extensions > Smart Product Badges. All fields can be set at default, website and store view scope.

General Settings

Setting	Default	What it does
Enable Smart Badges	Yes	Master switch. When disabled the storefront script is not output and the badge endpoint returns no badges.
Maximum Badges Per Product	3	Upper limit of badges shown on one product (1 to 10). Values outside the range fall back to 3.
Badge Combination Mode	Priority Mode (Single Source)	"Priority Mode (Single Source)" shows badges from one source only, in the order manual attribute, then rules, then automatic badges. "Collect All Mode (Multiple Sources)" merges all sources up to the maximum.
Show Multiple Rule Badges	No	Only shown in Collect All Mode. When enabled every matching rule contributes a badge; otherwise only the highest-priority rule does.
Show Auto Badges With Manual/Rules	No	Only shown in Collect All Mode. When enabled automatic badges are added even if a manual or rule badge exists; otherwise automatic badges appear only when no other badge matched.

Display Settings

Setting	Default	What it does
Multiple Badge Layout	Vertical Stack (Default)	Arrangement of several badges in the same position: "Vertical Stack (Default)", "Horizontal Row", "Grid Layout (2 columns)" or "Compact (Overlapping)".
Badge Spacing	gap-2	Gap class between badges. The storefront maps `gap-1`, `gap-2`, `gap-3` and `gap-4` to 0.25, 0.5, 0.75 and 1 rem.

Badge Colors

This group contains only an explanatory note. Default colours for the badge types are CSS variables (--badge-sale, --badge-new, --badge-hot, --badge-limited, --badge-exclusive, --badge-bestseller, --badge-trending, --badge-featured) with fallback values defined in the storefront template; etc/theme-config.json lists the same colour set for the theme configuration provided by Panth_Core. A rule with its own "Badge Color" overrides the variable.

Config paths: smart_badge/general/enabled, smart_badge/general/max_badges, smart_badge/general/badge_combination_mode, smart_badge/general/show_multiple_rule_badges, smart_badge/general/auto_badges_with_manual, smart_badge/display/badge_layout, smart_badge/display/badge_spacing.

Badge rules (admin grid)

Menu: Panth Extensions > Smart Badges > Manage Badges (URL smartbadge/rule/index). The grid shows ID, Status, Priority, Rule Name, Badge Type, Custom Text, Custom Color, Product IDs, Category IDs and Created, supports inline editing, and offers the mass actions "Delete" and "Change Status" (Enable / Disable). "Create New Badge Rule" opens the form, which has these sections:

Section	Fields
Basic Information	Rule Name (required), Enable Rule, Priority (0 to 100, default 50), Store Views (required, default All Store Views), Customer Groups (leave empty for all groups), Badge Type
Design	Badge Text (leave empty to use the type default), Badge Color (hex colour picker), Badge Icon (FontAwesome icon list)
Badge Image	Upload Badge Image (JPG, JPEG, PNG, GIF, WebP, max 2 MB); when set, the image is rendered inside the badge
Animation	Animation Type: None, Pulse, Bounce, Shake, Glow, Rotate, Flip, Swing, Tada, Jello, Heartbeat, Fade In, Fade Out, Slide In Left, Slide In Right, Slide In Up, Slide In Down, Zoom In, Zoom Out, Flash, Rubber Band, Wobble, Head Shake, Roll In, Roll Out
Display Conditions	Specific Products (comma-separated IDs with a "Browse Products..." chooser), Categories (comma-separated IDs with a "Browse Categories..." chooser); leave both empty to apply to all products
Smart Conditions	Price Range (Min / Max), Stock Level (Less than / Greater than / Equals), Discount Percentage (Greater than / Less than / Equals), Product Age (Days) (Newer than / Older than), Stock Status (In Stock / Out of Stock), Customer Rating (Greater than / Less than / Equals, in stars), Sales Count (Greater than / Less than / Equals)
Schedule	Start Date, End Date
Advanced Styling	Border Radius (px), Font Size (px), Font Weight, Padding (top, right, bottom, left), Opacity (%), Box Shadow, Border Width (px), Border Style, Border Color
Display Settings	Display On, Use Same Position for All Views, Badge Position, Category Page Position, Product Page Position, Slider Position

Position options: Top Left, Top Right, Bottom Left, Bottom Right, Top Center, Bottom Center, Center Left, Center Right.

Product attributes

setup:upgrade adds three attributes to the "Product Details" group of every product: "Product Badge" (select: "-- Auto Detect --" or one of the eight badge types), "Custom Badge Text" and "Custom Badge Color" (hex colour). A value in "Product Badge" is treated as a manual badge and takes precedence over rules and automatic badges.

Usage

Where badges render

view/frontend/layout/default.xml adds the bundled FontAwesome stylesheet (Panth_SmartBadge::fontawesome/css/all.min.css), Panth_SmartBadge::css/badge-styles.css and the block Panth\SmartBadge\Block\Badge with template Panth_SmartBadge::product-badges.phtml at the end of the body on every page. The template outputs a script that:

detects product cards (form.product-item, Hyva .card.card-interactive items, Luma li.product-item, generic .product-item) and the product detail gallery (#gallery-main, #gallery, Fotorama, .product.media, and similar);
reads the product ID from data-product-id, the body class product-<id> or the product URL;
collects the product IDs found in the same pass and sends them in one POST request to smartbadge/badge/batch with a JSON body {"product_ids": [<id>, ...]} (at most 60 IDs per request; larger pages are split into several requests), and caches the answer per product for the page view, so products added later by AJAX or sliders only request the IDs not seen before;
inserts the badges into the image container, grouped by position, using the layout and spacing from configuration;
treats a product card inside .slick-slide, .swiper-slide, .owl-item, [data-slider], .product-slider or .carousel as a slider item;
re-runs on DOM changes (MutationObserver) so products loaded by AJAX or sliders also receive badges.

If no product ID or image container can be found for an element, that element is skipped and a warning is written to the browser console.

How badges are chosen for a product

If "Enable Smart Badges" is off, no badges are returned.
Manual badge: the "Product Badge" attribute, with "Custom Badge Text" and "Custom Badge Color" applied when set.
Rule badges: all active rules ordered by priority (highest first). A rule is skipped when its Store Views do not include the current store view (All Store Views matches every store view) or when its Customer Groups list is not empty and does not include the visitor's customer group (NOT LOGGED IN for guests). A rule matches when its schedule is current, the product is in its product ID list (if any) or in one of its categories or their parents (if any), and every enabled smart condition is true. Conditions are evaluated with the product final price, the CatalogInventory stock item, approved reviews, the bestsellers report and wishlist items.
Automatic badges: discount percentage badge (only while the special price is inside its "Special Price From" / "To" dates), "NEW" badge (product created within 30 days) and "Only N left" badge (quantity 1 to 10). These thresholds are fixed in code.

In Priority Mode the first source that yields a badge wins and only the top rule badge is used. In Collect All Mode the manual badge is given priority 100, rule badges 50 and automatic badges 10, the list is sorted and cut to "Maximum Badges Per Product".

Admin behaviour

Saving a rule validates the name (required), priority (0 to 100), badge colour (#RRGGBB) and image file name, and normalises product, category, store view and customer group ID lists.
Save, delete, mass delete, mass status, inline edit, upload and validate accept POST requests only. Inline editing in the grid changes only Status, Priority, Rule Name, Custom Text and Custom Color.
In the admin, the FontAwesome stylesheet is loaded only on the Manage Badges grid and the rule form, and badge-admin.css only on the grid; other admin pages are not affected.
Uploaded badge images are checked against an allowed extension list, the detected MIME type (JPEG, PNG, GIF or WebP), a 2 MB size limit and the Panth_Core upload extension policy; SVG files are not accepted. Replaced images are not deleted from pub/media/smartbadge/.
Rule schedules are evaluated at request time; there is no cron job in this module.

Templates that can be overridden

view/frontend/templates/product-badges.phtml (the injector script and its CSS, loaded by layout)
view/frontend/templates/badge.phtml (a server-side badge markup template for the current product; not loaded by the module layout, available for theme use)
view/frontend/templates/badge_list.phtml (placeholder, not loaded by the module layout)
view/frontend/web/css/badge-styles.css
Admin form templates view/adminhtml/templates/rule/assign-products.phtml, smart-conditions.phtml and advanced-styling.phtml

Developer Notes

Module name: Panth_SmartBadge; Composer package: mage2kishan/module-smart-badge; namespace: Panth\SmartBadge; version 1.1.0.
Loads after Panth_Core, Magento_Catalog, Magento_CatalogInventory, Magento_Review and Magento_Customer.
Key classes:
- Helper\BadgeHelper::getProductBadges($product) returns the final badge array for a product and applies the combination mode.
- Model\BadgeService::getRuleBadgesForProduct($product) evaluates rules; Model\ConditionEvaluator evaluates schedules and smart conditions. Besides the seven conditions exposed in the form, the JSON stored in smart_conditions also accepts wishlistCount, attribute (with code, operator equals / not_equals / contains, value) and dateRange (from, to) keys.
- Block\Badge (storefront block), Controller\Badge\Batch (POST smartbadge/badge/batch, JSON body {"product_ids": [...]}, at most 60 IDs, answers {"products": {"<id>": [badges]}} with an empty list for unknown or disabled products) and Controller\Badge\Get (POST smartbadge/badge/get for a single product_id, kept for theme scripts). Both have CSRF validation disabled so they can be called from any theme script.
- Model\Rule with Model\ResourceModel\Rule (table panth_smart_badge_rule), Model\Badge with Model\ResourceModel\Badge (table panth_smart_badge), Model\Rule\DataProvider for the UI form.
- Option sources under Model\Config\Source: BadgeType, BadgeOptions, Animation, BadgeLayout, CombinationMode, DisplayOn, FontAwesomeIcons, Position, StoreViews, CustomerGroups.
Admin controllers under Controller\Adminhtml\Rule (index, new, edit, save, delete, inlineEdit, massDelete, massStatus, upload, validate, productsGrid, categoryTree); productsGrid and categoryTree back the form choosers.
Routes: frontend smartbadge, admin smartbadge.
ACL resources: Panth_SmartBadge::config (configuration section), Panth_SmartBadge::badges, Panth_SmartBadge::rule (grid and menu), Panth_SmartBadge::rule_save, Panth_SmartBadge::rule_delete.
etc/di.xml defines the virtual grid collection Panth\SmartBadge\Model\ResourceModel\Rule\Grid\Collection for smartbadge_rule_listing_data_source. etc/frontend/di.xml registers the module with Panth\Core\ViewModel\ThemeConfig. There are no plugins, observers, cron jobs, console commands or web API endpoints.
Database tables from etc/db_schema.xml: panth_smart_badge (badge_id, name, type, label_text, background_color, text_color, position, priority, is_active, css_class, animation, created_at, updated_at) and panth_smart_badge_rule (rule_id, badge_id, rule_type, conditions, product_ids, category_ids, is_active, priority, badge_image, smart_conditions, schedule_from, schedule_to, name, badge_type, badge_text, badge_color, badge_icon, animation, badge_style, image_settings, display_on, position_category, position_product, position_slider, position_all, use_same_position, store_ids, customer_group_ids, created_at, updated_at). store_ids and customer_group_ids are comma-separated ID lists; an empty value or store ID 0 means all.
Setup patches: Setup\Patch\Data\AddBadgeAttribute, Setup\Patch\Data\AddCustomBadgeAttributes, Setup\Patch\Schema\AddBadgeImageColumn, Setup\Patch\Schema\ConvertToUtf8mb4 (converts both tables to utf8mb4 so emoji icons can be stored).
FontAwesome is served from view/base/web/fontawesome/ (css/all.min.css, webfonts, LICENSE.txt) on the storefront and in the admin, so the module needs no Content Security Policy entry.

Uninstallation

bin/magento module:disable Panth_SmartBadge
composer remove mage2kishan/module-smart-badge
bin/magento setup:upgrade
bin/magento setup:di:compile
bin/magento cache:flush

The tables panth_smart_badge and panth_smart_badge_rule, the smart_badge/* rows in core_config_data, the product attributes product_badge, badge_custom_text and badge_custom_color, and uploaded images in pub/media/smartbadge/ are not removed automatically. Do not remove Panth_Core if other Panth modules use it.

Support

Product page: kishansavaliya.com/magento-2-smart-badge.html
Contact: kishansavaliya.com/contact
Email: kishansavaliyakb@gmail.com
GitHub issues: github.com/mage2sk/module-smart-badge/issues

Documentation

USER_GUIDE.md covers installation, verifying the module, global configuration, creating a badge rule, badge types, smart conditions, display settings, advanced styling, scheduling, badge images, animations, managing rules in the grid and troubleshooting.

License

Commercial software license. See LICENSE.txt in this repository.

Changelog

See CHANGELOG.md.

mage2kishan / module-smart-badge

Package info

Security

Statistics