Documentation Home

Module Installation

The product type module requires configuration and database changes.
There are optional DB scripts to load sample data for the Broadleaf demo.

Configuration Changes

Step 1. Add the dependency management section to your parent pom.xml:

<dependency>
    <groupId>com.broadleafcommerce</groupId>
    <artifactId>broadleaf-product-type</artifactId>
    <version>1.0.0-GA</version>
    <type>jar</type>
    <scope>compile</scope>
</dependency>

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

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

Step 3. 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="
           resourceUrlEncodingFilter,
           blAdminRequestFilter,
           hiddenHttpMethodFilter,
           blLog4jMappedDiagnosticContextFilter,
           blJSCompatibilityRequestFilter,
           blAdminOmsRequestFilter,
           blAdminTypedEntityRequestFilter"/>
    </sec:filter-chain-map>
</bean>

Data Changes

Schema Changes

If you are allowing hibernate to create and modify your tables, this will be done automatically when you restart with the new configuration settings.

Otherwise, you will need to generate the SQL to customize your Broadleaf implementation. See the Broadleaf Schema Upgrade Documentation for details.

Admin Security Changes

To maintain product types in the Broadleaf admin, you will need to load new permissions. The recommended changes are located in the following file and include a new Admin menu item with access granted to the Admin and Merchandiser roles.

    /config/bc/sql/load_product_type_admin_security.sql,\

Note: In development, you can automatically load this SQL by adding this file to the blPU.hibernate.hbm2ddl.import_files property in the development-shared.properties file.

Optional Data Changes

If you want to augment the heat clinic demo data with country product types data, reference the additional SQL file in development-shared.properties in the blPU.hibernate.hbm2ddl.import_files property:

/config/bc/sql/samples/load_product_type_admin_security.sql

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.