Documentation Home

BroadleafCommercePrivate - 5.1.0-GA

This release includes several merchandising improvements and an upgrade to Thymeleaf 3.0.

Upgrading to this release requires some database migration steps that are outlined in each respective module. Migration notes from 5.0.x will be made available in our documentation set.

Noteworthy Changes

Product Add-Ons (Enterprise License Required)

Simply put, a Product Add-On defines complementary items that are intended to be sold in conjunction with a given Product. For example, a bag of charcoal may be an Add-On for a grill.

Product Add-Ons are also great for defining product bundles by relating a set of Products that are intended to be sold as a single unit. We've decided to deprecate the ProductBundle domain and begin modeling bundles using Product Add-Ons. For details on migrating towards these add-on based bundles, see the ProductType module. If you wish to continue using your deprecated ProductBundles, they will continue to work just as they did in 5.0, but you'll need to set the following property to allow Admin users to create new ProductBundles:


On the other hand, Product Add-Ons are not a simple Product to Product relationship. From the business side, Add-Ons are highly customizable. Business users have the ability to select a particular Product, or allow their customers to select one or multiple add-on(s) from a predefined set. Additionally, business users can set quantity restrictions for each Add-On and have several options for defining the pricing scheme used for the additional product in the Add-On context.

Product Add-On Admin Configuration

Once the business-side configuration is complete, customers will then have the power to define the exact set of Product Add-ons, or the exact bundle, that they want to purchase.

Product Add-On Site Configuration

Promotion Messages (Enterprise License Required)

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 configured to display in different contexts including catalog browsing, product detail pages, and in the customer’s cart. Additionally, for Offers, business users can create Promotion Messages that specifically target the Offer’s qualifier products or targeted products.


Cart Rules (Enterprise License Required)

Cart rules give your business the ability to automatically manipulate a customer’s cart based on recently added items or the state of the cart. We expect these to often be used in conjunction with an offer or sale. For example, let’s say we have a BOGO offer where you get a free hot sauce if you buy a T-shirt. In this case, you may want to automatically add the hot sauce to the customer’s cart, just after they add a T-shirt.

Sales (Enterprise License Required)

Sales within Broadleaf allow you to affect the price of products and SKUs during the customer's browsing experience. This is in contrast to an offer, which only affects the price once SKUs have been added to the cart.

Purchase-based Customer Segments (Enterprise License Required)

Purchase-based customer segments give users the ability to identify sets of customers based on their previous spending patterns. Using these groupings, businesses can target these customers for particular offers, sales, or targeted content.


Thymeleaf 3.0 support

Thymeleaf 3 is now supported OOB along with backwards compatibility with Thymeleaf 2. With this additional support additional new features are available, such as full HTML5 support and the ability to decouple HTML from Thymeleaf logic, along with a noticeable performance increase.

For more information about migration see 5.1 Thymeleaf Migration

Theme aware classpath Thymeleaf TemplateResolvers

Previously, the ThemeTemplateResolver only allowed you to put templates in the /WEB-INF/ of your deployed application. Instead you can instantiate a template resolver that is based off of your classpath but still adds the current theme as a subfolder:

<bean id="customClasspathResolver" class="org.broadleafcommerce.presentation.resolver.BroadleafThemeAwareTemplateResolver">
    <property name="prefix" value="classpath:/common_templates/templates/" />
    <property name="suffix" value=".html" />
    <property name="templateMode" value="HTML5" />        
    <property name="characterEncoding" value="UTF-8" />
    <property name="cacheable" value="${}"/>
    <property name="cacheTTLMs" value="${}" />
    <property name="order" value="300"/>

This makes it much easier to share templates between themes.


Removed all JAXRS Support

This was supported in the 5.0 line but was deprecated when we moved our APIs to Spring MVC. All default JAXRS support has been removed from Broadleaf, you will need to update your endpoints to use Spring MVC instead to take advantage of any new features.

Moved API classes out of core and into its own module

All of our API support (like BroadleafWebServiceException, Jackson ObjectMapper modifications, default endpoint classes, etc) has moved out of broadleaf-framework-web and into broadleaf-rest-api. The class names are all the same so simply add the dependency to your pom.xml:


and then re-organize imports to resolve any compilation errors. Most of the classes moved their packages from org.broadleafcommerce.core.web.api to

API Endpoint Updates

Based on real-world use cases we have updated our default API endpoints to be more representative of what you would need if you were only using Broadleaf in an API capacity. Check out our Swagger documentation for the most up to date definitions.

An at-a-glance view of the issues that were closed in this release:

Critical Bugs(2)

  • Fix Error Where the Customer Was Null When Going to Site as Customer from Admin
  • Changed BLC_STORE column name to "STORE_OPEN"

Major Bugs(4)

  • Removed @Nonnull Annotation from SimpleRule.getMatchRule
  • Made 'additionalOffers' unable to filter and sort and template cleanup
  • Fix issue causing js to fail
  • Fixed NPE when configuring Solr Cloud

Minor Bugs(7)

  • Ensure "entityFriendlyName" is added to the model on an add failure
  • Disabled Primary Entity Buttons until the Page Is Loaded to Prevent NumberFormatExceptions
  • Remove CPH that is no longer relevant after domain changes
  • Asset Selector URL field change fix
  • Fix Failing 5.1 Tests
  • Added FieldBuilder extension point
  • The relationship between StructuredContentTemplate and FieldGroup is too restrictive


  • Add Thymeleaf 3 and common presentation support


  • Deprecate BundleOrderItems
  • Remove StoreImpl Conditional Weave for STORE_OPEN
  • Make urlhandler more efficient
  • Refactored out the Searchable interface from attributes and the map fields annotation
  • Remove any long-deprecated framework JSP support
  • Refactor isAssignableFrom into neutral location
  • Added Margin Between ListGrid Buttons
  • Remove the deprecated GoogleAnalyticsProcessor, HeadProcessor and outdated Thymeleaf patch
  • Remove the transitive CMS dependency on broadleaf-framework
  • Move admin index field classes out of the framework and into the admin-module
  • Remove the deprecated API classes and drop all JAXRS support
  • Added new field persistence provider for typed entities
  • Multiple Offers per OfferCode
  • Refactor how PromotionMessages are used in the Cart
  • Rename PromotionMessage's Media property
  • Sort promotion messages by priority
  • New Interfaces and Convenience methods
  • Deprecate legacy product bundles
  • Refactor blcRootCategory
  • Added FieldBuilder extension point
  • Offer & PriceList PromotionMessages
  • Refactor blcRootCategory
  • Refactored out the Searchable interface from attributes and the map fields annotation

Total Resolved Issues: 37