Product Labels

Show rule-based labels ("badges") such as Sale -20%, New or Only 3 left on product images, under the product name or after the price, on Luma and Hyvä. This guide covers installation, configuration, creating labels and day-to-day use.

• Demo (Luma): https://demo.softawarecommerce.com/women/bottoms-women/pants-women.html
• Demo (Hyvä): https://demo.softawarecommerce.com/hyva/gear/bags.html
• Admin demo: https://demo.softawarecommerce.com/try-admin/product-labels
• Changelog: Release notes · Questions: FAQ

1. Requirements

Stock conditions read the CatalogInventory tables (cataloginventory_stock_item). Setups with Multi-Source Inventory have not been tested.

2. Installation

Install with Composer from the SoftAware Commerce repository. The access keys are in your account; see Composer access.

composer config repositories.softaware composer https://repo.softawarecommerce.com
composer config --auth http-basic.repo.softawarecommerce.com PUBLIC_KEY PRIVATE_KEY
composer require softaware/module-product-labels
bin/magento setup:upgrade
bin/magento setup:di:compile            # production mode only
bin/magento setup:static-content:deploy # production mode only
bin/magento cache:flush

Hyvä: the module registers itself for Hyvä's Tailwind build and adds its label CSS from view/frontend/tailwind/tailwind-source.css. After installing, rebuild your theme CSS (npm run build in the theme's web/tailwind folder). Luma and themes based on it load css/product-labels.css and need no build step.

To update later: composer update softaware/module-product-labels, then the same bin/magento commands.

3. Quick start

1. Go to Softaware > Product Labels > Manage Labels and click Add New Label.
2. Enter a Name (only shown in the admin), leave Enabled on and choose the Store Views.
3. Under Conditions, switch on On Sale and enter a Minimum Discount (%) such as 5.
4. Under Appearance on Listings, set Text to -{discount_percent}%, Shape to Rounded rectangle (pill) and pick the colours. The preview on the right shows the result.
5. Click Save Label. In "Update on Save" mode the label is applied to matching products straight away; open a category with discounted products to see it.

4. Managing labels

Softaware > Product Labels > Manage Labels lists every label with its preview, status, priority, store views, From/To dates, the number of products it is assigned to and the last update.

• Add New Label opens the label form.
• Apply All Labels Now re-evaluates all labels for the whole catalogue (a full reindex). On large catalogues this can take a while; the nightly cron does the same.
• Actions (mass actions): Enable, Disable, Delete. Enabling or disabling re-applies the selected labels at once.

General settings of a label

Customer groups, dates and the real discount are checked when the page is rendered. When a dated label starts or ends, the hourly cron cleans the page cache of the label's products, so cached pages follow within the hour.

5. Conditions

A product gets the label when it matches all conditions you switch on, the price range, the product types and the attribute conditions. A label with no conditions at all applies to every product.

6. Appearance

Each label has two independent appearance sections: Appearance on the Product Page and Appearance on Listings (category pages, search results, widgets, related products, up-sells and cross-sells). Switch either off with Show on Product Page or Show on Listings. A live preview next to each section shows the label on a sample product (sample values: discount 20%, 3 left, 5 days).

Variables in the label text

7. What your customers see

Labels appear on category pages, search results, catalogue widgets, related products, up-sells, cross-sells and the recently viewed and compared widgets, and on the product page on the main gallery image, under the product name or after the price.

On Hyvä the labels use the module's Hyvä templates and the CSS added to the Tailwind build:

On phones the labels stay on the product image (Luma left, Hyvä right):

Product page placement: on Luma the label sits on the Fotorama gallery stage; on Hyvä it uses the gallery's gallery.additional container. On listings, "Under the product name" is shown just above the price box.

8. Configuration

Stores > Configuration > Softaware > Product Labels (also under Softaware > Product Labels > Configuration).

General (default, website and store view scope)

Label Conditions (default scope)

Indexing (default scope)

9. Indexing and cron

The module adds two indexers under System > Index Management: Softaware Product Labels (by label) and Softaware Product Labels (by product). They share one index table and can run in "Update on Save" or "Update by Schedule" mode.

• Update on Save: saving a label applies it at once; saving a product re-checks that product.
• Update by Schedule: changes are picked up by Magento's indexer cron (this also covers mass attribute updates and imports, which do not fire product save events).
• Only changed rows are written, and only the page cache of products whose labels changed is cleaned.

Cron jobs (group index):

Magento cron must be running (bin/magento cron:run from the system crontab).

10. Command line

bin/magento softaware:product-labels:apply                    # re-evaluate all labels
bin/magento softaware:product-labels:apply --label=3 --label=5 # only these labels
bin/magento softaware:product-labels:apply --time-dependent   # only labels with new, stock, best seller, sale conditions or dates
bin/magento softaware:product-labels:check 24-MB02            # labels indexed for a SKU, per store view
bin/magento indexer:reindex softaware_product_label

11. Permissions (ACL)

In System > Permissions > User Roles > Role Resources:

12. Troubleshooting

13. Uninstall

bin/magento module:disable Softaware_ProductLabels
composer remove softaware/module-product-labels
bin/magento setup:upgrade

The tables softaware_product_label, softaware_product_label_store, softaware_product_label_customer_group and softaware_product_label_index and the uploaded label images in pub/media/softaware/productlabels are not deleted by these commands; remove them by hand if you no longer need them.