Attribute Keys
Product and variant details, like a product's name, color, or size, come from the SCAYLE Commerce Engine as attributes, each identified by a key such as name or color. The Storefront Application V3 collects the attribute keys it reads in one file, /src/shared/constants/attributeKeys.ts. If your shop's product data uses a different key, for example itemColor instead of color, you change it once in that file instead of in every mapper. A mapper is the server code that turns Storefront API data into the shape a page uses, see Extending the SDK.
Three attributes are mandatory: the product name and brand, and the variant size. The SDK ProductMapper reads name and brand, and the SDK OrderMapper reads size for the variants of order items, all with fixed keys that the constants in the file don't reach. Your product data has to carry them, or you override the mapper. See Change a key for your shop. Every other key in the file is optional, and a product without a value for it maps to an empty field. The list isn't closed: you can add constants for more attributes and read them in your mappers.
Where the keys are used
Only server code imports the constants. A mapper uses an attribute constant in two places. First, when it tells the SCAYLE Storefront API which attributes to fetch. Second, when it reads the fetched value back off the product. Page components don't import them, because they receive the mapped values.
The product mapper requests attributes through include getters. Includes serves the listing products of the product listing page, search, recommendations, the wishlist, the basket, and CMS product sliders. DetailedIncludes serves the product detail page and requests all attributes. VariantIncludes and ImageIncludes list the variant and image attributes by key. A key you add for a listing product goes into Includes. The sibling products in Includes and DetailedIncludes each have their own withKey list.
The snippet is trimmed to the color field. The real file requests more attributes and maps more fields.
Use getFirstAttributeValue or getAttributeValuesByName (both from @scayle/storefront/shared) to read values off a product's or variant's attribute map. getFirstAttributeValue returns a single value or undefined, and getAttributeValuesByName always returns an array. Pick the one that matches the shape your mapper needs. When a product has no value for a key, the mapped field is empty, for example an empty string for color, or undefined for badge.
The keys the Storefront Application V3 ships with
This is the complete list in attributeKeys.ts.
| Constant | Key | Used for |
|---|---|---|
ATTRIBUTE_KEY_NAME | name | Product display name. |
ATTRIBUTE_KEY_BRAND | brand | Brand label. |
ATTRIBUTE_KEY_COLOR | color | Color label shown on the product detail page, listing page, and order history. |
ATTRIBUTE_KEY_STOREFRONT_BADGE | storefrontBadge | Badge label shown on the product detail and listing pages. |
ATTRIBUTE_KEY_DESCRIPTION | description | Product description. |
ATTRIBUTE_KEY_SIZE | size | Variant size label. |
ATTRIBUTE_KEY_PROMOTION | promotion | Requested for listing products, so the promotions that apply to a product can be resolved. |
ATTRIBUTE_KEY_IMAGE_TYPE | imageType | Names the image view an image belongs to. The image view selector on the product listing page and the search page reads it. |
ATTRIBUTE_KEY_APPLY_PADDING | applyPadding | Flag indicating that an image should be padded within its frame. |
ATTRIBUTE_KEY_FIT_SIZE | fit_size, an attribute type | Fit-and-size section on the product detail page. |
ATTRIBUTE_KEY_EXTRAS | extras, an attribute type | Care instructions section on the product detail page. |
ATTRIBUTE_KEY_DESIGN | design, an attribute type | Design and styling notes section on the product detail page. |
@scayle/storefront exports SUBSCRIPTION_ATTRIBUTE_KEYS, the four variant attribute keys that subscriptions depend on: subscriptionEligibility, subscriptionAvailableIntervals, subscriptionTerm, and subscriptionCancellationPolicy. They are subscription attributes from the SCAYLE Panel, and the SDK reads them itself, so they stay the same regardless of how a shop names its other attribute keys. The product mapper adds them to its variant include with withKey: [ATTRIBUTE_KEY_SIZE, ...SUBSCRIPTION_ATTRIBUTE_KEYS].
Change a key for your shop
If your shop's product data uses different attribute keys than the defaults above, update the constant's value in attributeKeys.ts, not the places that import it. Every mapper that reads ATTRIBUTE_KEY_COLOR, for example, picks up the new key.
fit_size, extras, and design are attribute types, not attribute keys. The product mapper collects every attribute whose type equals the constant's value, whatever its key. A shop that sets one of these constants to an attribute key gets an empty section and no error. Set them to the attribute types your shop uses in the SCAYLE Panel instead, see the product detail page constraint.
The SDK mappers read three keys themselves, with fixed keys that the constants do not reach:
ProductMapperreadsnameandbrandto fill the name and brand of every listing product, detail product, and sibling.OrderMapperreadssizeto fill the size of an order item's variant.
Changing ATTRIBUTE_KEY_NAME or ATTRIBUTE_KEY_BRAND changes only what the application requests and reads itself, such as getPath, the order mapper in your project, and the brand filter of the CMS. It does not change what the base mapper reads. A shop whose data uses other keys for these three ends up with products without a name or brand, and order items without a size. If your shop uses other keys, override mapBaseProduct and mapSibling in ProductMapperService, or mapVariant in OrderMapperService, and read your keys there.