General Overview

Promotion messages give business users the ability to actively promote offers and sales throughout the customer-facing site by displaying a message or image with a product listing. These messages can be gathered from both offers and sales, and from the front-end perspective, are treated as equals.

Promotion messages are intended to be displayed in the context of a product listing. In most cases, promotion messages should be gathered using the following Thymeleaf processor:

<th:block th:with="promoMessages=${#promotion_messages.getProductPromotionMessages(product, 'EVERYWHERE')}">
    <div class="promotion-message" th:unless="${#lists.isEmpty(promoMessages)}">
        <span th:text="${promoMessages[0].message}"></span>
    </div>
</th:block>

To gather a product's promotion messages, you'll need to pass in the product object and specify where it should be placed. In return, you will recieve a list of PromotionMessageDTOs which include offer and sale messages for the specified product and location, sorted by their priority properties.

Message Type

Out of box, Broadleaf provides two types of messages to promote your offers and sales for a product: a plain text message and an image. Both of these are passed to the front-end through a PromotionMessageDTO.

Placement

Promotion messages can be configured to display in different contexts including catalog browsing, product detail pages, in the customer’s cart, or everywhere. To see the full set of placement locations, see PromotionMessagePlacementType.java.

Additionally, the placement of promotion messages can factor in the locale that they are intended to be show in.

Offers

For offers, you get a bit more control of where a promotion message should be shown by indicating whether the message should be shown for target products, qualifier products, or both. For example, let’s say you have a BOGO offer where customers get a free hot sauce if they buy a T-shirt. In this case, you may want to promote the offer through a message on the T-shirt (the qualifier) only.

In the Cart

The only location that the PromotionMessageVariableExpression should not be used, is in your cart templates. In this context, we can make use of OrderItems, rather than Products. This gives us the ability to know precisely which promotion message should be applied. For instance, if an order item is the target of an offer, then we can gather the offer's target promotion messages. Additionally, we have similar information for identifying promotion messages for offer qualifiers and sales. When order items are priced, promotion messages are gathered and attached to each OrderItem. This information is eventually used in the front-end templates to display cart information.

On the other hand, if a message is not found using this additional OrderItem data, then it will attempt to gather any promotion messages through the product.

Promotion Message in Cart vs Cart Message

If you are familiar with Broadleaf, then you may have used Offer's cart message property to show a message in the cart, once the offer has been applied. The difference between the cart message and in-cart promotion messages, is that the cart message is intended to indentify the applied offer, whereas promotion messages are intended to advertise potential offers.

Priority

After multiple offer and sale promotion messages are gathered and passed to the front-end templates, how do you know which to display?

Using the priority property on the promotion messages, we can identify the most important message to display.