empiricompany / maho-product-labels
Rule-driven product labels (badges) for category listings, product pages, widgets and carousels
Package info
github.com/empiricompany/maho-product-labels
Type:maho-module
pkg:composer/empiricompany/maho-product-labels
Requires
- php: >=8.5
Requires (Dev)
Suggests
None
Provides
None
Conflicts
None
Replaces
None
README
Rule-driven product labels (badges) for category listings, product pages, widgets and carousels. One rule defines the condition and the look; the label then appears the same everywhere.
What it does
- Rules use the framework rule engine and the catalog price rule condition widget, so the admin screen is the one you already know. Website and customer group selectors behave like the catalog rules; there is no per store view visibility.
- Text and image are per store view (store view
0is the default, other store views fall back to it). Position and colors belong to the label and are shared. - An index table (
productlabels_index) holds the association rule → product → website → customer group. The storefront runs one query per page, whatever the number of rules; nothing is evaluated per product. - Values are computed at render time from data the product already carries
(
price,final_price, stock quantity, attributes), so pages stay cacheable. Dates can also be relative to today (is on or after today,is on or before todaywith a day offset): those are resolved by the nightly index rebuild, never per request. - A read-only grid in the rule shows the products it labels, with the fields of the product grid, so you can check the result before and after a rebuild.
Requirements
- PHP >= 8.5
- Maho Commerce
Installation
composer require empiricompany/maho-product-labels ./maho migrate
Enable the module in Stores → Configuration → Catalog → Product Labels, then fill the index once:
./maho productlabels:reindex
Configuration
A rule has four tabs.
| Tab | Contents |
|---|---|
| General | name, code, status, position, colors, websites, customer groups, validity dates, priority |
| Conditions | the rule conditions, with the same widget as the catalog price rules |
| Label | one card per store view, grouped by website: text, image, colors and a live preview that stays visible while scrolling |
| Products | read-only grid of the products the rule labels, taken from the index |
The Products grid shows the columns of Catalog → Manage Products.
| Column | Field |
|---|---|
| ID | entity_id |
| Name | name |
| Type | type_id |
| Attrib. Set Name | attribute_set_id |
| SKU | sku |
| Price | price, in the base currency |
| Qty | stock quantity |
| Visibility | visibility, as icons |
| Status | status, as icons |
| Websites | the websites of the product |
Every column has its filter and the grid pages through the results; there is no edit action.
The grid reads the index, so it has no row until the rule is saved or indexed. A product that is not visible individually never appears in a listing or on its own page, so the indexer skips it: its label would never be printed.
Usage
In a template
<?= $this->helper('productlabels')->render($_product) ?>
Place it inside an element with position: relative (the module ships the
pl-labels-host class for that). For the product page:
<?= $this->helper('productlabels')->render(Mage::registry('current_product')) ?>
A label with position content does not belong to the image overlay: it goes in the text block
of the card, through a second call. Add it after the price, in both view modes:
<?= $this->helper('productlabels')->renderContent($_product) ?>
render() prints every position but content; renderContent() prints only content, inside a
flex wrapper so several labels sit on one line.
For custom code, Mage::helper('productlabels')->getLabels($product) returns the resolved
label data.
Placeholders
| Placeholder | Value |
|---|---|
{discount_percent} |
discount percentage between price and the real final price |
{discount_amount} |
discount amount, formatted with the store currency |
{price} / {final_price} |
formatted prices |
{qty} |
stock quantity |
{attribute:code} |
product attribute value, printed by attribute type (see below) |
A placeholder that cannot be computed for a product renders empty, and a text that ends up empty removes the label instead of printing an empty badge.
{attribute:code} follows the attribute type:
| Attribute type | Printed |
|---|---|
select |
the option label (Cotton) |
multiselect |
the option labels joined with , (Cotton, Linen) |
boolean |
the option label, translated (Yes / No) |
price |
the value formatted with the store currency (€28.00) |
text, textarea |
the value with tags stripped and whitespace collapsed |
| missing or empty | nothing |
The value is read from the store the rule is evaluated on (see the note below), not from the store view the customer is browsing.
Use cases
Conditions are the catalog price rule ones, with two extra operators for date attributes:
is on or after today and is on or before today, whose value is a day offset
(0 = today, -7 = a week ago, 30 = in a month). A date attribute with a normal operator
(is, equals or greater than, equals or less than) takes a fixed date from the calendar.
| Case | Conditions | Label text | Look |
|---|---|---|---|
| New arrivals | Set Product as New from Date is on or before today 0 AND Set Product as New to Date is on or after today 0 |
NEW |
top left, white on blue |
| Discount badge | Special Price greater than 0 |
-{discount_percent}% |
top right, white on red |
| Free shipping | Price equals or greater than 50 |
Free shipping |
bottom right, white on green |
| Promotion ending soon | Special Price To Date is on or after today 0 AND Special Price To Date is on or before today 3 |
Last days |
top left, white on orange |
| Coming soon | Set Product as New from Date is on or after today 7 |
Coming soon |
top left, white on indigo |
| Attribute value as text | Material is Cotton |
{attribute:material} |
top right, white on black |
| Brand badge | Brand is Acme (any brand you sell) |
{attribute:brand} |
bottom right, white on slate |
| B2B price | Price equals or greater than 500, customer groups = Wholesale |
B2B price |
bottom left, white on navy |
Notes:
- Rules are evaluated by the indexer against the default store of the first website of the rule, so store-scoped attributes (dates included) are read from that store's values; leave the values at All Store Views when you want one rule for every website.
- Website and customer group selectors work like the catalog rules; empty means "all". Two rules on the same corner are ordered by priority (lower first) and Stop Further Labels.
- Text and image are per store view with fallback to the default one, so
NEWcan beNOVITÀon the Italian store view without duplicating the rule. - An image replaces the text and the colors: position still applies, but the label is drawn from the image only, with no background and no padding around it.
- Stock quantity is not a condition (it lives in the stock tables, not in the product
attributes), but
{qty}is available as a text placeholder: a rule such asMaterial is Cottonwith the textOnly {qty} leftprints the quantity at the last rebuild.
Example: a new-arrivals label that maintains itself
- Create a rule, name it
New arrivals, positionTop Left, text color#ffffff, background#0ea5e9. - Conditions:
Set Product as New from Date is on or before todaywith0days, add a second conditionSet Product as New to Date is on or after todaywith0days, both in the same ALL group. - Label tab:
NEWon the default store view,NOVITÀon the Italian one; leave the image empty to render the text. - Nothing else: the nightly rebuild adds the label when a product enters its new window and removes it when the window closes.
Example: print the value of a product attribute
- Rule
Material badge, positionTop Right, background#111827. - Conditions:
Material is Cotton(or drop the condition to label every product). - Text:
{attribute:material}.
The placeholder is formatted by the attribute frontend, so a select attribute prints its
option label (Cotton), not the stored id; a multiselect prints every label, a boolean
prints Yes/No, a price attribute prints the value with the store currency.
Index
./maho productlabels:reindex # all rules ./maho productlabels:reindex --rule=5 # one rule ./maho productlabels:reindex --product=42 # one product
A nightly cron rebuilds the index (prices, stock and dates change without a product save). Saving a rule or a product reindexes only what changed.
Theme integration
The module ships css/productlabels.css and the pl-label markup. The rule reproduces the badge
of the base theme (24px height, 11px side padding, 8px radius, 1px border, 12px bold uppercase
text, the same shadow as the discount badge), so a label looks like the other badges of the
storefront on any theme and the core stays untouched. The markup also carries the badge class,
so a theme can style the component and adjust .pl-label on top of it.
The rule colors are mapped onto the badge variables (--badge-bg, --badge-fg,
--badge-color) from --pl-bg and --pl-fg, with the theme tokens as fallback
(--color-error, --color-error-content) and then fixed values.
The module styles the base theme list too, but it cannot add the template calls: a theme that does not call the helper has no labels and no error.
License
Open Software License 3.0 (OSL-3.0). See LICENSE.txt.