Broadleaf Microservices
  • v1.0.0-latest-prod

Advanced Tags (and Badges)

Data Model

Advanced Tag Data Model
Figure 1. Advanced Tag and Related Entities Data Model

Advanced Tags

A "tag" represents a unique purchasing attribute for a product such "new", "on sale", "fairtrade", etc. Tags may also be configured with a rich text message and some controls for how or where they should be displayed on the storefront. By default, tags are facetable and can be configured to be searchable.

Tip
AdvancedTags may be associated with a Product with a Product Tag.

Configuring Search to Use Tags

AdvancedTags are typically used for faceting during the shopping experience and may also be used as search keywords. The name property is what is used by default for both of these purposes and is translatable. The searchableByName controls whether the tag is used just as a facet or also as a search term for related Products. This flag is exists because it may not always make sense for a tag to be searchable such as for "20% Off" or "New".

Setting up Facets

If using Broadleaf’s Search Service, you can create a Search Field that targets an advancedTags collection added to the Product during the indexing process to create one or more facets and enable searchability. One way to go about this is to create multiple Search Fields to serve as facets that target tags by type and a separate Field targeting tags where searchableByName is true to enable searching for them only. A reason to split the tags by type is to allow a more customer friendly experience such as grouping all the discount tags in a "Discount Type" facet and all the feature tags under a "Feature" facet. This is also convenient way to organize tag facets.

Tip
Search Field property paths support JSON path syntax. Therefore, you can create a Field targeting advancedTags and filtering by a specific type. Here’s an example that targets all the FEATURE tags: advancedTags[?(@.type == "FEATURE")].name.

Customizing Tag Types

Do note that the type property is related to a default enum, DefaultTagType. These are just recommendations and ideas for how you can type your tags; don’t feel married to the default values and feel free to add more types. No logic is directly tied to these types in the code, although the default facets do use them as described previously (this can be changed in the admin).

Tip
The type values can be easily adjusted in the admin using Metadata Augmentations. Look for the "Customize Form" button in the admin when viewing Advanced Tags or other entities. Then hover over the field and click on the gear icon to the right of it.

Caveat about Indexing and Tag Active Date Ranges

It’s important to note that the indexing process will index the tags and product tags that are active at the time of the index. This may mean that the index will be out of date as time progresses because there isn’t an event caused by the current date exceeding the active date range. Currently, the way to resolve this is to do a regular full reindexing process. This will pick up any change in activeness for the various entities related to a product.

Note
This issue only affects which tags show up as facet values and are used as search terms. If the tag is not active, it will not be displayed on any related product as a badge because hydrating the display values onto the results is handled separately from indexing.
Note
We are considering other automated ways of handling changes in activeness because of the date range.

Displaying Badges for Tags

AdvancedTags can also include details for displaying them on related products. This can just be the name but can also be a custom asset using badgeAsset or some custom HTML using badgeMessage. Whether the tag is displayed on the product at all is controlled by the position property. The default is NONE, or not displayed.

The general idea is to display a badge on the product’s primary asset whether on a browse, search, or product details page. Thus, the default values available for position are:

  • TOP_LEFT

  • TOP_RIGHT

  • TOP_CENTER

  • TOP_JUSTIFIED

  • CENTER_LEFT

  • CENTER_RIGHT

  • CENTER

  • CENTER_JUSTIFIED

  • BOTTOM_LEFT

  • BOTTOM_RIGHT

  • BOTTOM_CENTER

  • BOTTOM_JUSTIFIED

  • NONE

These values can be customized and the specific values will only take on meaning in the storefront app itself. Normally, only one badge will be displayed per position. This is controlled by the sort position on the parent Product and the priority property on the tag itself, the priority will break ties.

Tip
The position values can be easily adjusted in the admin using Metadata Augmentations. Look for the "Customize Form" button in the admin when viewing Advanced Tags or other entities. Then hover over the field and click on the gear icon to the right of it.
Tip
It’s also recommended to hide the badge when it is being actively faceted on, e.g., when a customer is filtering results by "New". This is because the badge is redundant as all the results will have it. By hiding it, the customer will be able to focus on other tags or details that distinguish the remaining results from each other, e.g., "this one is on sale" or "this one is fairtrade".

BLC_ADVANCED_TAG

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

NAME

A friendly identifier for the tag. Can be used as a search term on the storefront if SEARCHABLE_BY_NAME is true. This will also be displayed as the facet value.

ACTIVE_START_DATE

Start of when this tag should be active.

ACTIVE_END_DATE

End when this tag is not longer active. Unset indicates that it is always active.

BADGE_MESSAGE

Message to display on a storefront such "New" or "Fairtrade" as a badge. This should support rich text (HTML) as well as plain text.

BADGE_ASSET

An asset that should be displayed for this tag.

SEARCHABLE_BY_NAME

Whether storefront users can find products (or other entities) with this tag by its NAME.

POSITION

Defines the position over a display component this tag should be displayed such as the "top-left" of a Product’s image on a list or details page. If multiple tags have the same position, then their relative order on a product or their PRIORITY will determine which is displayed.

TYPE

Defines the type of this tag such as "key feature" or "discount". This allows categorizing tags to enhance user’s ability to prioritize related tags such as only showing one "discount" tag even if a product has several. Moreover, this can be used to group tags when used as facets so that you can show a Feature facet with only features as the possible values, Discount Type facet, etc.

PRIORITY

Priority of this tag relative to other tags that may share the same position or type. This provides a way to pick on tag over another when there is a conflict. In the context of specific product, the priority is used to break ties between Product Tags with the same sort position.

Broadleaf Common Data Features

Advanced Tags are Application Trackable and Sandbox Trackable.

Product Tags

A ProductTag defines the relationship between a Product or one of its Variants and an Advanced Tag. A product or variant can have multiple ProductTags and determine relative priority via ordering them in the admin. This relationship will also be used during indexing to hydrate the tags for a product to enable faceting, searching, and boosting. The ProductTag may define its own active date range separate from the related tag since the tag can be longer lived than its relationship with a product or variant, such as a "New" tag.

BLC_PRODUCT_TAG

Field Description

ID

Unique row ID

CONTEXT_ID

Logical ID. Allows for sandbox versions.

ACTIVE_START_DATE

Start of when this tag should be active.

ACTIVE_END_DATE

End when this tag is not longer active. Unset indicates that it is always active.

PRODUCT_CONTEXT_ID

Soft ref to the parent Product.

VARIANT_ID

Soft ref to the parent Variant. May be null if not associated with a Variant.

PRIORITY

Soft ref to the related AdvancedTag.

Broadleaf Common Data Features

Product Tags are Catalog Trackable and Sandbox Trackable.