Add metadata to facet values

You can associate metadata with facet values so it can be displayed on your store.

Associating metadata with facet values is most commonly used to display images instead of text. For example, you might want to display swatch images instead of names for Color facets, or display stars instead of a numeric value for an Average Customer Rating facet.

Any key:value pair can be added as metadata to be returned along with the standard facet value information; however, the key name must contain an underscore character, for example x_imageUrl or tool_tip_text, to ensure it does not conflict with existing system keys. JSON objects cannot be used as a value, however multiple values can be provided as a list, for example:

"x_imageUrl" : ["/images/one.png", "/images/two.png" ]

Add metadata to a facet value

The following procedure shows an example of adding images to an “Average Customer Rating” facet.

1. Update the Facets data store with metadata for each value using the following - POST /gsdata/v1/cloud/facets/<facet-name>, using the system property of key to define which value the metadata should be added to, for example, “key”: “Red” for the value Red.

     POST /gsdata/v1/cloud/facets/product.x_averageCustomerRating
   {
       "items": [
    { 
        "key" : "5",
        "x_imageUrl" : "/general/5-star.png"
    }, 
    {
        "key" : "4",
        "x_imageUrl" : "/general/4-star.png"
    },
    {
        "key" : "3",
        "x_imageUrl " : "/general/3-star.png"
    },
    {
        "key" : "2",
        "x_imageUrl " : "/general/2-star.png"
    },
    {
        "key" : "1",
        "x_imageUrl " : "/general/1-star.png"
    }
   ] }
   
   

2. Run an index either by triggering a publish event, or by calling the index endpoint, for example, POST /ccadmin/v1/search/index { “op”: “partial” }

Notes:

• Values will only be available once an index has run, so if the facet is new and a publish has not been run, this will return an error.
• If you need to retrieve the values for the facet, you can call the “dimvals” endpoint, for example: GET /gsadmin/v1/cloud/dimvals/product.x_decade/children

Use metadata on the storefront

Once you've added the metadata to facet values and the search indexing operation has completed, the metadata will be returned in the search API endpoint responses alongside the existing facet value data. Metadata can also be easily accessed in storefront widgets.

The following snippet shows a knockout if binding that displays an image from the Commerce media library. When this binding is added to the Product Listing widget on the Search Results layout, displays an image when iterating through the facet values.

<ko:if: $data.properties[‘x_imageUrl’]-->
      <img data-bind=”attr:{src: ‘file/’+$data.properties[‘x_imageUrl’]}” />
</ko>