Package com.broadleafcommerce.catalog.domain.product.option

Class ProductOption

java.lang.Object
com.broadleafcommerce.catalog.domain.product.option.ProductOption
All Implemented Interfaces:
com.broadleafcommerce.data.tracking.core.EmbeddedContextStateAware, com.broadleafcommerce.translation.mapping.SubIdentifiable, Serializable, Comparable<ProductOption>
public class ProductOption extends Object implements Serializable, Comparable<ProductOption>, com.broadleafcommerce.data.tracking.core.EmbeddedContextStateAware, com.broadleafcommerce.translation.mapping.SubIdentifiable

A "product option" encapsulates additional, variable information about a Product explicitly designed for customer-facing input. This can be info necessary for distinguishing particular variants such as shirt size, color, or material, or it can be some custom user-input such as a name to emboss on the back of a jersey. Finally, it can even drive additional products that should be added to the cart along with the product that it is configured for.

Product Option comes configured with out of the box types, documented below.

Item Choice

The customer is selecting from a group of products or variants that will be added to their cart along with the parent item. The choices that the customer can select from can come from a category or an explicitly-defined set of products or variants.

Variant Distinguishing

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. This means that there should exist a unique variant for every combination of each option's AttributeChoice#allowedValues(s). 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

While Variant/SKU generation is one use case of the variants, a user can also add a single variant that maps to specific combinations. In the example above, a user might only care about a 'Small Black' and 'Medium Large' shirts. The customer-facing frontend should react to this and only display the values for which there exist Variant.getOptionValues().

All of the variant distingushing attributes are similar to the item attribute type in that the values that the customer fills out are eventually stored as attributes on the item in the cart.

Item Attribute and Order Attribute

Dictates where the customer input should be stored once received. Most commonly this can be used for dynamic customer input (like a gift card message or name on the back of a jersey) but picking from a set of pre-defined values is supported here as well.

Validation

If allowed values or AttributeChoice.required are specified then the user input is validated against it when adding to the cart. If a item attribute or order attribute allows dynamic input, you can add additional validation to it. For instance, when requesting text for embossing a name on a jersey the length of the message and characters used need to be restricted. The support defining a AttributeChoice.validationRule, , and AttributeChoice.errorMessage. Normally, the validation rule will be a regular expression; however, a field for AttributeChoice.validationType is also supported to define some other means of validation.

It may also be important to control when this extra validation occurs during the shopping flow. Some values may need to be validated immediately when an item is added to cart while others should be validated once the order is submitted. Thus, AttributeChoice.validationStrategy has been provided. The default supported values are enumerated in DefaultValidationStrategy.

Author:
Phillip Verheyden (phillipuniverse)
See Also:

  • Constructor Details

    • ProductOption

      public ProductOption()

  • Method Details

    • getAttribute

      public <T> T getAttribute(String name)

    • compareTo

      public int compareTo(@NonNull ProductOption o)
      Specified by:
      compareTo in interface Comparable<ProductOption>

    • getId

      public String getId()
      Specified by:
      getId in interface com.broadleafcommerce.translation.mapping.SubIdentifiable
      See Also:
      • SubIdentifiable.getId()

    • getTemplateContextId

      public String getTemplateContextId()
      If this option came from an OptionTemplate this allows data synchronization if the template is updated.
      Returns:
      the id of the OptionTemplate that this option was created from or null if this was created in isolation

    • isAddedByReference

      public boolean isAddedByReference()
      Denotes whether this option was added from an OptionTemplate by reference rather than being embedded on the Product. If true, then this Option needs to be hydrated from the OptionTemplate referenced by templateContextId before responding to client requests, e.g., before Product Details, Admin, or Indexer requests, to read the Product that owns this option.
      Returns:
      whether this option was added from an OptionTemplate by reference rather than being embedded on the Product

    • getLabel

      public String getLabel()
      The label shown to customers when displaying this option. This helps communicate to customers how they should fill out the input
      Returns:
      the display shown to customer for this option

    • getType

      public String getType()
      Controls both how the customer should be inputting values to fill out this option as well as storage of where the value will go once added to the cart.
      Returns:
      which type of input this option is configured for
      See Also:

    • getDisplayOrder

      public Integer getDisplayOrder()
      The ordering of this option in relation to other options on the page. Can be null which indicates ordered last.
      Returns:
      how this option should display in relation to other options
      See Also:

    • getSearchOnOption

      public Boolean getSearchOnOption()
      If the product option is of type DefaultProductOptionType.VARIANT_DISTINGUISHING, this allows searching based on this product option. For example, if the product were a T-Shirt with three colors, three documents for each color would be indexed.

    • getItemChoice

      public ItemChoice getItemChoice()
      Configuration for the DefaultProductOptionType.ITEM_CHOICE. Drives customer selection of an additional item to add to their cart
      Returns:
      configuration if the type of this option is an DefaultProductOptionType.ITEM_CHOICE, otherwise null

    • getAttributeChoice

      public AttributeChoice getAttributeChoice()

      Configuration when the type of this option is one of:

      1. DefaultProductOptionType.VARIANT_DISTINGUISHING - drives customer further specifying their choices into a specific Variant that contains a unique SKU code, pricing concerns, etc.
      2. DefaultProductOptionType.CART_ITEM_ATTRIBUTE - Customer input will flow directly in the item attributes within their cart
      3. DefaultProductOptionType.CART_ATTRIBUTE. Customer input will flow directly in the global cart attribute. Any previously-set attribute should be replaced with new values.
      Returns:
      attributeChoice if the type of this option is an DefaultProductOptionType.VARIANT_DISTINGUISHING, DefaultProductOptionType.CART_ITEM_ATTRIBUTE or DefaultProductOptionType.CART_ATTRIBUTE, otherwise null

    • getAttributes

      public Map<String,Object> getAttributes()
      Miscellaneous attributes for this tag.
      Returns:
      Miscellaneous attributes for this tag.

    • getContextState

      public com.broadleafcommerce.data.tracking.core.EmbeddedContextState getContextState()
      A subset of Tracking information to expose the context state for this object.
      Specified by:
      getContextState in interface com.broadleafcommerce.data.tracking.core.EmbeddedContextStateAware
      Returns:
      a subset of Tracking information to expose the context state for this object

    • setId

      public void setId(String id)
      Specified by:
      setId in interface com.broadleafcommerce.translation.mapping.SubIdentifiable
      See Also:
      • SubIdentifiable.getId()

    • setTemplateContextId

      public void setTemplateContextId(String templateContextId)
      If this option came from an OptionTemplate this allows data synchronization if the template is updated.
      Parameters:
      templateContextId - the OptionTemplate this option was created from

    • setAddedByReference

      public void setAddedByReference(boolean addedByReference)
      Denotes whether this option was added from an OptionTemplate by reference rather than being embedded on the Product. If true, then this Option needs to be hydrated from the OptionTemplate referenced by templateContextId before responding to client requests, e.g., before Product Details, Admin, or Indexer requests, to read the Product that owns this option.
      Parameters:
      addedByReference - whether this option was added from an OptionTemplate by reference rather than being embedded on the Product

    • setLabel

      public void setLabel(String label)
      The label shown to customers when displaying this option. This helps communicate to customers how they should fill out the input
      Parameters:
      label - the display shown to customers for this option

    • setType

      public void setType(String type)
      Controls both how the customer should be inputting values to fill out this option as well as storage of where the value will go once added to the cart.
      Parameters:
      type - the type of input that the drives customer selection, defaults from DefaultProductOptionType
      See Also:

    • setDisplayOrder

      public void setDisplayOrder(Integer displayOrder)
      The ordering of this option in relation to other options on the page. Can be null which indicates ordered last.
      Parameters:
      displayOrder - how this option should display in relation to other options
      See Also:

    • setSearchOnOption

      public void setSearchOnOption(Boolean searchOnOption)
      If the product option is of type DefaultProductOptionType.VARIANT_DISTINGUISHING, this allows searching based on this product option. For example, if the product were a T-Shirt with three colors, three documents for each color would be indexed.

    • setItemChoice

      public void setItemChoice(ItemChoice itemChoice)
      Configuration for the DefaultProductOptionType.ITEM_CHOICE. Drives customer selection of an additional item to add to their cart
      Parameters:
      itemChoice - configuration only when type is DefaultProductOptionType.ITEM_CHOICE

    • setAttributeChoice

      public void setAttributeChoice(AttributeChoice attributeChoice)

      Configuration when the type of this option is one of:

      1. DefaultProductOptionType.VARIANT_DISTINGUISHING - drives customer further specifying their choices into a specific Variant that contains a unique SKU code, pricing concerns, etc.
      2. DefaultProductOptionType.CART_ITEM_ATTRIBUTE - Customer input will flow directly in the item attributes within their cart
      3. DefaultProductOptionType.CART_ATTRIBUTE. Customer input will flow directly in the global cart attribute. Any previously-set attribute should be replaced with new values.
      Parameters:
      attributeChoice - configuration for customer-driven values that flow into an attribute

    • setAttributes

      public void setAttributes(Map<String,Object> attributes)
      Miscellaneous attributes for this tag.
      Parameters:
      attributes - Miscellaneous attributes for this tag.

    • setContextState

      public void setContextState(com.broadleafcommerce.data.tracking.core.EmbeddedContextState contextState)
      A subset of Tracking information to expose the context state for this object.
      Specified by:
      setContextState in interface com.broadleafcommerce.data.tracking.core.EmbeddedContextStateAware
      Parameters:
      contextState - a subset of Tracking information to expose the context state for this object

    • equals

      public boolean equals(Object o)
      Overrides:
      equals in class Object

    • canEqual

      protected boolean canEqual(Object other)

    • hashCode

      public int hashCode()
      Overrides:
      hashCode in class Object

    • toString

      public String toString()
      Overrides:
      toString in class Object