Broadleaf Microservices
  • v1.0.0-latest-prod

Product Options and Templates

Data Model

Product Option Template and Template Group Data Model
Figure 1. Product Option Template and Template Group Data Model

*Added in Broadleaf 1.8.2

Product Options

The ProductOption domain encapsulates additional, structured information a seller wants to capture from a customer during the ordering process. This information can be necessary for distinguishing particular variants such as shirt size, color, or material, or it can be some custom user-input like a name to emboss on the back of a jersey. As such, ProductOptions support specifying a set of allowed values that conform to a specific type—validation for those allowed values is supported.

Moreover, a ProductOption can be configured so that the customer can select from a set of products or variants directly such as for a configurable bundle. In such cases, this domain allows specifying minimum and maximum selectable quantities per item in the bundle as well setting pricing that overrides the selected item’s usual pricing when merchandised separately. The price of the item can even be marked as already included in the parent bundle’s.

OptionTemplates provide a means to persist ProductOptions independent of any Product to aid in reuse. Additionally, OptionTemplateGroups have been provided to aggregate related OptionTemplates. When ProductOptions are added via an OptionTemplate, they may be added by reference at generation.

When added by reference, the ProductOption’s templateContextId will hold a reference to the ID of the template. A flag will also be set on the option indicating it should be hydrated from the template before being returned to a caller. Hydration is configured to take place when Products are retrieved for commerce, admin, and indexer requests. With this method, any changes made to the template will be reflected by the options that reference it, and the option will be read-only from the Product management view.

Otherwise, a copy of the ProductOption will be embedded in the Product, meaning that changes to the template will not affect options previously generated from it, and that the option will be managed from the product.

Tip
 See the Catalog Service’s product details documentation to learn more about how Broadleaf handles product details hydration.

Generating Variants from Product Options

Since ProductOptions tend to be used in distinguishing Variants, it is common to allow automatic generation of Variants based on the options added to a Product. To specify that a ProductOption should be used to distinguish variants, simply set that option’s type to VARIANT_DISTINGUISHING. This means that there should exist a unique variant for every combination of each option’s allowedValues. Therefore, if a there is a "shirt" product that has "size" (Small, Medium, Large) and "color" (Black, White, Red) options and each option is set to be used in variant distinguishing, then there should exist 9 variants:

  1. Small Black

  2. Small White

  3. Small Red

  4. Medium Black

  5. Medium White

  6. Medium Red

  7. Large Black

  8. Large White

  9. Large Red

Option Templates and Template Groups

The OptionTemplate domain allows the creation of ProductOptions from a template, allowing users to avoid recreating the same option for multiple products over and over again. Often, these are grouped into an OptionTemplateGroup to provide a sort of product type. For instance if you are selling T-Shirts, all of the T-shirts might have a product option "size" and "color", but they all have the same sizes and same colors. This might be configured with an OptionTemplateGroup of "T-shirts", that contain a 'Size' and 'Color' template, used to create products off of.

Important
 If a ProductOption's addedByReference is true, the options generated from the template will be kept in sync with changes to the template. Otherwise, the ProductOption will not be affected by the template.

BLC_OPTION_TEMPLATE

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

NAME

The friendly name of the template

PREFER_ADD_BY_REF

Sets the default preference for this template when associated with a product. This can be overridden when the template is associated with a Product. If the option is generated from a template, true means that the option will reference the template, false means that the option will be embedded in the product.

OPTION_TEMPLATE_CONTEXT_ID

When a ProductOption is stored on a Product after being generated from an OptionTemplate, this is the ID of the template it came from. This can be used to allow synchronization between the template and options generated from it.

OPTION_LABEL

Text shown to customers when displaying this option such as on a product details page.

OPTION_TYPE

Determines the kind of option to generate: Variant distinguishing, item choice, cart item attribute, or cart attribute. This controls how a customer selects or inputs values and how this option is stored on a cart.

OPTION_DISPLAY_ORDER

The order relative to other options in which this option should be displayed to a customer.

OPTION_PRODUCT_CONTEXT_ID

When a ProductOption is stored on a Product after being generated from an OptionTemplate, this is the ID of the owning Product.

IS_OPTION_SEARCHABLE

If true, Product Options of VARIANT_DISTINGUISHING type will be searchable in indexer requests. By default, this means that a Solr document will be created for each allowed value of the option, e.g., a Red Shirt, Black Shirt, and Silver Shirt document instead of just a Shirt document.

IC_CHOICE_KEY

Unique identifier for the option when the OPTION_TYPE is ITEM_CHOICE. This key is used during validation of a cart item’s configuration to relate the parent cart item representing the product that owns the ProductOption to a dependent item that represents the chosen item(s). The validation primarily ensures that the minimum and maximum quantities are met.

IC_TARGET_TYPE

Defines the type of item being chosen when OPTION_TYPE is ITEM_CHOICE. Default targets are CATEGORY, SPECIFIC_PRODUCTS, or SPECIFIC_VARIANTS.

IC_SELECTION_TYPE

Defines the type of selection a customer can make when choosing item choices. This can be CHOOSE_ONE (only one of the optional items can be selected) or CHOOSE_MULTIPLE (more than one optional item can be selected).

IC_MAXIMUM_QUANTITY

When the option’s OPTION_TYPE is ITEM_CHOICE, this defines the maximum quantity a customer can choose for the item(s) selected.

IC_MINIMUM_QUANTITY

When the option’s OPTION_TYPE is ITEM_CHOICE, this defines the minimum quantity a customer must choose for the item(s) selected.

IC_PRICING_MODEL

Defines how to price the item choice(s) in regard to the Product that owns ProductOption. Default models are INCLUDED_IN_PARENT (the price of the item choices are already included in the parent’s price) or ADD_TO_PARENT (the price of the item choices will be added to the parent product’s)

IC_OVERRIDE_PRICE

Defines the unit price for the item choices if the IC_PRICING_MODEL is ADD_TO_PARENT. This will override the pricing on the underlying Product or Variant being chosen.

IC_DISCOUNT_ALLOWED

If the IC_PRICING_MODEL is ADD_TO_PARENT, determines whether item choices can receive discounts.

IC_PRICING_KEY

If the IC_PRICING_MODEL is ADD_TO_PARENT, defines a system-wide unique ID for configuring pricing of the item choice(s). This can be used by external pricing services to identify the choice(s).

IC_DEFAULT_PRODUCT_CONTEXT_D

When the option’s IC_TARGET_TYPE is SPECIFIC_PRODUCTS, this defines the ID of the default item choice to select.

IC_DEFAULT_VARIANT_CONTEXT_ID

When the option’s IC_TARGET_TYPE is SPECIFIC_VARIANTS, this defines the ID of the default item choice to select.

IC_DEFAULT_PROD_IN_CAT_CTX_ID

When the option’s IC_TARGET_TYPE is CATEGORY, this defines the ID of the default product in the category to select.

IC_CATEGORY_CONTEXT_ID

When the option’s IC_TARGET_TYPE is CATEGORY, this defines the ID of the Category from which to gather products to use as item choices.

IC_SPECIFIC_CHOICES

When the option’s IC_TARGET_TYPE is SPECIFIC_PRODUCTS or SPECIFIC_VARIANTS, this holds the manually-curated items that the customer can choose from. This provides additional granularity in providing override pricing on a choice-by-choice basis instead of being shared across all choices.

AC_ATTRIBUTE_NAME

When the option’s OPTION_TYPE is VARIANT_DISTINGUISHING, CART_ITEM_ATTRIBUTE, or CART_ATTRIBUTE, this defines the name of the attribute on the cart or cart item. This is not displayed to the customer, but is an internal, system key.

AC_TYPE

When the option’s OPTION_TYPE is VARIANT_DISTINGUISHING, CART_ITEM_ATTRIBUTE, or CART_ATTRIBUTE, defines the type of attribute. This controls what is displayed to the customer to select or input a value for the attribute, and can one of COLOR, SIZE, BOOLEAN, TEXT, DATE, TEXT_AREA, DECIMAL, INTEGER, or SELECT.

AC_REQUIRED

When the option’s OPTION_TYPE is VARIANT_DISTINGUISHING, CART_ITEM_ATTRIBUTE, or CART_ATTRIBUTE, this determines whether a customer must select or input a value for the attribute.

AC_VALIDATION_STRATEGY

When the option’s OPTION_TYPE is VARIANT_DISTINGUISHING, CART_ITEM_ATTRIBUTE, or CART_ATTRIBUTE, this determines when the ProductOption is validated. The default possibilities are ADD_ITEM (when the parent product is added to the cart) and SUBMIT_ORDER (when the order is submitted).

AC_VALIDATION_TYPE

When the option’s OPTION_TYPE is VARIANT_DISTINGUISHING, CART_ITEM_ATTRIBUTE, or CART_ATTRIBUTE, this determines how the ProductOption is validated. The default type is REGEX.

AC_VALIDATION_RULE

If AC_VALIDATION_TYPE is REGEX, then this field holds the regular expression used to validate the ProductOption.

AC_ERROR_MESSAGE

If the validation fails, this is the message to display.

AC_ERROR_CODE

If the validation fails, this is the associated error code. This could also be used as a message key.

AC_ALLOWED_VALUES

When the option’s OPTION_TYPE is VARIANT_DISTINGUISHING, CART_ITEM_ATTRIBUTE, or CART_ATTRIBUTE, this provides a means to specify the exact options that can be selected from by a customer. This could be where color or size options are defined.

BLC_OPTION_TEMPLATE_GROUP

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

NAME

The friendly name of the template group

TEMPLATE_CONTEXT_IDS

Context IDs of the OptionTemplates included in this group

Broadleaf Common Data Features

OptionTemplate and OptionTemplateGroup entities are Catalog Trackable, which includes Sandbox Trackable behavior.