Documentation Home

Module Installation

Steps to enable this module in your custom Broadleaf Commerce project

Steps

Step 1 Pull this dependency into your core/pom.xml:

<dependency>
    <groupId>org.broadleafcommerce</groupId>
    <artifactId>broadleaf-product-type</artifactId>
</dependency>

This assumes that you are using the Broadleaf BOM that pins all version information. If not, you will need to also add a <version> qualifier

Step 2. You'll need to include the blAdminTypedEntityRequestFilter Web Filter in your admin module to facilitate the management of typed entities. In the file, applicationContext-admin-filter.xml, ensure that this filter is placed last in the filter chain.

<bean id="blPostSecurityFilterChain" class="org.springframework.security.web.FilterChainProxy">
    <sec:filter-chain-map request-matcher="ant">
        <sec:filter-chain pattern="/**" filters="
           ...
           blAdminTypedEntityRequestFilter"/>
    </sec:filter-chain-map>
</bean>

Note: If you have a Spring Boot based project, then this step is not necessary. In that case, the filter will be automatically ordered according to its org.springframework.core.Ordered#getOrder() return value, when the resource is registered with Spring.

Data Changes

Schema Changes

To add all of the necessary database tables and columns for this module, please follow the Liquibase update documentation.

Admin Security Changes

The data in the following SQL file is required to establish Admin sections and permissions for this module:

classpath:/config/bc/sql/load_product_type_admin_security.sql

This file is automatically included if you have set blPU.hibernate.hbm2ddl.auto=create and you have not set import.sql.enabled=false in your properties files. If you are not using Hibernate's auto DDL process and are using Liquibase, you can add a new changeSet that references this file:

<?xml version="1.1" encoding="UTF-8" standalone="no"?>
<databaseChangeLog xmlns="http://www.liquibase.org/xml/ns/dbchangelog" xmlns:ext="http://www.liquibase.org/xml/ns/dbchangelog-ext" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog-ext http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-ext.xsd http://www.liquibase.org/xml/ns/dbchangelog http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.5.xsd">
    <changeSet author="broadleaf" id="some-unique-id">
        <sqlFile path="config/bc/sql/load_product_type_admin_security.sql" encoding="utf8" stripComments="true" />
    </changeSet>
</databaseChangeLog>

Finally, you can unpack the downloaded .jar file and look at the files in the config/bc/sql folder to execute this sql manually.

Demo Data

Demo data is included in classpath:/config/bc/sql/samples.

Product Bundle Migration (Optional)

Since there are a high number of moving pieces related to the configuration of Product Bundles, we believe that it is best to defer this data migration to our clients. With that being said, we'd like to provide the following information to give you a better understanding of the capabilities of Product Add-On based Product Bundles.

To migrate to the new Add-On based Product Bundles, you'll need to introduce the ProductType enterprise module. This module will leave all existing ProductBundle records in place, but will no longer allow you to add bundles from the Product admin section. Instead, this module introduces an admin section specifically for Product Bundles. This section leverages Products of type BUNDLE and Product Add-Ons allowing you to create configurable bundles.

There are a few aspects that should be condidered when migrating your data:

  1. Product/Sku Selection Bundles are now built from the Product level instead of the SKU level, which allows the customer to specify the exact SKU that they want. Additionally, with Product Add-Ons, we now support Choose One and Choose Multiple typed bundle items which allow customers to select a SKU, or multiple SKUs, from a predefined list of Products.
  2. Bundle Item Quantity Product Add-Ons allow you to specify whether the bundle should include a fixed quantity for each bundle item, or a quantity range. If a range is used, then customers can choose any quantity within that range to complete their bundle.
  3. Pricing In many ways pricing is the same, but instead of controlling the pricing model at the bundle level, each of Product Add-On has the ability to set its pricing scheme. The price of the add-on can be Included in Parent or Add To Parent. If Add To Parent, then you are given the opportunity to override the Product's base price or each of the Product's SKU prices, in the bundle context.

Once you have migrated all of your bundles, you can run the following SQL to archive all legacy Product Bundles. In addition, you'll need to reindex Solr to guarantee that the archived bundles are no longer appear on the customer-facing site.

UPDATE BLC_SKU as sku
       JOIN BLC_PRODUCT as product ON sku.SKU_ID = product.PRODUCT_ID
       JOIN BLC_PRODUCT_BUNDLE as bundle ON bundle.PRODUCT_ID = product.PRODUCT_ID
SET    sku.ARCHIVED = 'Y', product.ARCHIVED = 'Y';

Additionally, we’ve introduced functionality to the consumer-facing site as it relates to product bundles. Before an order containing a bundle is eligible to be completed, the bundle in question must be configured. This can happen a couple different ways:

One approach is to add the bundle normally, just as a normal product. In the case that the bundle needs configuration, the system will allow it to be added to the cart, however the associated order item in the cart will be marked as containing an error. This bundle will need to be configured before checkout can be completed. To configure a bundle once it’s been added to the cart, we’ve introduced a new HTML partial to the cartProductsTable.html to handle any configuration messaging required: orderItemConfigureMessaging.html. Among other items in the partial we have a link with the class update-child-items which triggers the configuration process. The implementation of this processes is kicked off in cartOperations.js.

The other approach when working with configurable bundles is to require the customer to configure it before it can be added to the cart. We’ve implemented this method in our current versions of The Heat Clinic sample webstore. The HTML templates containing our “Add To Cart” buttons now have have additional logic to determine whether or not the product has child items. In this case, the button receives the css class configureItem which is handled in cartOperations.js. The user is presented with a modal allowing the user to customize their bundle. When a bundle doesn’t require any configuration, it is added directly to the cart, without any additional input from the customer.

Both of these approaches leverage several new methods located in the CartController.java and subsequently BroadleafCartController.java. The main methods to inspect include configure(…), reconfigure(…), and getProductDetails(…).

When implementing your own solution, be sure to see how we’ve built out our sample templates. Specifically, look at configure.html which defines the actual configure screen as well as all templates referenced by it.

For more detail on our demo implementation of this functionality, take a look at the latest 5.1 version of the DemoSitePrivate module.