Merge available and selected facet values

As the shopper navigates and selects facet values, the search response (by default) returns information about those selected facet values in the Breadcrumbs section.

This section applies to Open Storefront Framework (OSF) only.

In addition, there is a feature that allows those selected refinements to be returned alongside unselected refinements. For example, suppose a Color facet has the values Blue, Green, Red and Black. If Color is enabled for multiselect, after the shopper selects Blue, you can configure this feature to return Blue either directly above or below Red, Green and Black. This allows the shopper to more easily see which facet values have been selected, and deselect values they no longer want to see.

Keep the following points about this feature in mind:

This feature works only for facets that are enabled for multiselect. For example, This feature will not work with the product.category facet because product.category cannot be enabled for multiselect.
Selected values can be returned before the list of unselected facet values or at the very end of the list. There is no way to place the facet value back in its original location.
If you are limiting how many facet values are returned (using numRefinements in the configuration), selected refinements count toward that total. For example, if you configured numRefinements = 10 and the shopper has selected two, then Commerce returns eight unselected refinements.
This feature works only for facets that have been specifically configured to return using the Facet Ordering feature in the administration interface. Specifically, when configuring a Facet Ordering rule, there is the list of selected facets, and also a checkbox for Including Remaining Facets. Merged refinements will not be returned for facets that are included in the remaining facets list.

Configure merged facet values

The procedure for configuring merged selected facet values is similar to that for configuring the ordering of facet values. See Configure the order of facet values for more information.

The option to merge selected facet values is part of the facet's displayConfig parameter, as shown in the following example:

"displayConfig": {"sort": "rank,desc;alpha,asc",
                          "mergeRefinementsStrategy": "prepend"}

There are three possible values for mergeRefinementsStrategy:

prepend places selected refinements at the beginning of the available refinements list.
append places selected refinements at the end of available refinements list.
disable is the default behavior, essentially the same thing as not specifying mergeRefinementsStrategy at all.

Merged facet values example

This section describes how to configured merged facet values for a facet named product.x_color, which is enabled for multiselect.

First, issue a GET request to /gsadmin/v1/cloud/attributes/ATG/product.x_color. Remember that attribute configuration under /attributes/ATG/ is controlled by the catalog, and is overwritten with each catalog export process.

Next, modify the attribute configuration to include a displayConfig property. In this example, mergeRefinementsStrategy is configured alongside sort.

{
     "isWildcardEnabledInRecordSearch": false,
     "displayOrder": 4,
     "multiSelectType": "OR",
     "displayConfig": {
       "sort":
          "freq,desc;alpha,asc",
       "mergeRefinementsStrategy": "prepend"
     },
     "sourcePropertyNames": ["product.x_color"],
     "isAutogen": true,
     "isRecordSearchEnabled": true,
     "ecr:type":
          "facet",
     "mergeAction": "update"
   }

Next, issue a PUT or POST request to/gsadmin/v1/cloud/attributes/system/product.x_color. If you are creating this entry under /attributes/system for the first time, use POST. To update, use PUT. Placing this configuration under /attributes/system, overrides and merges configuration set under /attributes/ATG. This ensures that it won't be lost during the catalog export process.

This example sets a prepend policy for the merged refinements. This will return any selected facets before the unselected ones.

After making the configuration changes, you must publish the changes in order for them to take effect on your production storefront. For more information, see Publish Changes.

When you configure a facet with mergeRefinementStrategy to either append or prepend, additional properties are returned with each facet value. In the following sample response, four facet values are returned. The first two are unselected and the last two were selected by the shopper. Unselected refinements are marked with "status" = "available", Selected refinements are marked with "status" = "selected". When rendering the facet values, you may wish to render "status" = "selected" values with checkboxes to indicate they have been selected.

In both cases, the link represents the new navigation state after the shopper clicks that link. For instance, the link for the value Black (which was selected by the shopper) would return the shopper to a navigation state where Black is not selected.

For facets that are not configured to return merged facet values, the status attribute will not be returned.

{
           "count": 1,
           "link": "/_/N-467230046+4072391598+1391151473",
           "label": "Blue",
           "properties": {
             "DGraph.Spec": "Blue"
           },
           "status": "available"
         },
         {
           "count": 1,
           "link": "/_/N-467230046+4072391598+2667202907",
           "label": "Red",
           "properties": {
             "DGraph.Spec": "Red"
           },
           "status": "available"
         },
         {
           "count": 3,
           "link": "/_/N-4072391598",
           "label": "Green",
           "properties": {
             "DGraph.Spec": "Green"
           },
           "status": "selected"
         },
         {
           "count": 2,
           "link": "/_/N-467230046",
           "label": "Black",
           "properties": {
             "DGraph.Spec": "Black"
           },
           "status": "selected"
         }