- v1.0.0-latest-prod
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. |
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".
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.
|
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. |
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. |
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". |
| 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 |
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 |
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 |
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 |
Advanced Tags are Application Trackable and Sandbox Trackable.
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.
| 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. |
Product Tags are Catalog Trackable and Sandbox Trackable.