Skip to content

Shoppable Images

Decisions behind shoppable images: a picture with the products in it, shown by the shoppableImage block.

A model of its own, not a block's settings

A shoppable image is its own document (ShoppableImage, collection shoppableImages) with a service, rather than settings stored on a content block. Reasons:

  • One picture, many places. The same outfit or room goes on the home page, a category banner and the product page of every piece in it. Settings on a block would be copied into each placement and drift.
  • "Complete the look" needs a query. A product page asks which pictures contain this product, and a category page which pictures link to it. That is an indexed query on the image documents (items.skuId, categoryLinks); block settings are scattered over pages, collections, nodes and stereotypes and can't be searched that way.
  • Agents and the admin edit it as a thing. manageShoppableImages and the admin editor work on one record with validation in one place (ShoppableImageServiceImpl), as modifier groups do.
  • Site transfer. A document travels in one file with one remap (its picture), instead of rewriting configuration inside every placed block.

The block only names an image, by handle rather than id. Handles and product SKUs survive a site transfer unchanged, so placed blocks and pieces need no remapping; only the media id does.

Generic, not fashion

It started from a fashion demo ("shop the look"), but nothing in the model is about clothes. A piece is a product with an optional exact variant, or a partial choice of any variant groups (options: {colourway: Oatmeal} or {finish: Oak}), plus a quantity (two chairs, four jars). The words shoppers see are generic ("In this picture") and every placement can set its own heading ("Shop the look", "Shop the room", "Shop the recipe").

Buying from the picture

The block decides per piece, in ShoppableImageViews, the simplest way to buy that is still correct, so the template only formats:

  • one SKU left: Add to basket;
  • the SKUs left differ in exactly one group: a list of that group's values and Add to basket (the size, the common case);
  • more than one choice left, or a product type that needs more than a SKU and quantity: a link to the product page with the pictured choice preselected.

Add to basket is a form post to /basket, the product page's endpoint, so the basket's rules apply unchanged. The form lives in each piece's size panel (a <template> the script clones); the script sends it in the background through the shared add to basket (NovaUi.addToBasket, see Storefront Fragments), which swaps in the header basket and, where the theme has one, the mini basket's content as the server draws them. It then confirms in the panel and fires shoppable:basket-updated with those two fragments, for anything else on the page that follows the basket. Without JavaScript, Add is a link to the product page. Two-choice pieces (CHOOSE_TWO) list both groups and every combination's SKU, and the script finds the SKU from the two choices. The compact rows, the size panel and the lookbook reader are described in Lookbook reader. A partial choice is carried to the product page as ?o=<group code>:<value>, which variants.js reads alongside ?v=.

Storefront rules kept

  • No inline styles. Hotspot positions come from data, but they're written as data-x / data-y and applied by shoppable-image.js as custom properties, so StorefrontStyleRatchetTest doesn't count them. Without the script the hotspots stay hidden and the numbered list still works.
  • One template for the Nova family. It's an extension template in nova/extensions/, not a ui/ component (only one block uses it), styled in bdgr.css's "extension: shoppable image" section through public --shoppable-* tokens resolved into --shoppablec-*, following the component token rules. Atelier re-skins it by setting tokens only.
  • Markers stay out of the way. A solid numbered disc on each piece covered the very garment it named, so a hotspot rests as a 12px frosted dot and grows into the numbered disc on hover, focus or when its piece in the list is hovered (.is-active). The link itself stays a 44px tap target. Under (hover: none) the number shows on a 22px disc all the time, since it's the only way to match a marker to the list below. Labels set beside the picture with leader lines were considered and dropped: the lines still cross the subject, and a phone has no margin for them.
  • Text from message keys (shoppableImage.*), prices with #shopMoney.
  • Cached for 5 minutes per page. The block's model goes through the extensions' model cache (cachePolicy(), per site and page). Which products a shopper may see depends on their staff-only collections, which the framework puts in every cache key; nothing else in the model depends on the shopper (the stock is the site's, not the basket's chosen store's). Stock shown may be up to five minutes old, and Add to basket checks it again. A block can name several pictures (comma-separated handles), fetched together, so a page of looks is a block per chapter: the Ashgrove lookbook went from 18 blocks and about 110 queries to 3 blocks. The catalogue's variant groups, which every block reads, are cached (VariantGroupRepository, tiered, cleared on any write).

Admin

The editor is a bx- page with the picture beside the details and products (stacked on a phone). Hotspots are dragged with pointer events, so mouse, pen and touch all work, and can be moved with the arrow keys. The pieces are kept by the page script and saved as JSON in one form field, since placing hotspots needs the script anyway; the other fields are ordinary form fields.

MCP

shoppableImages and manageShoppableImages are in the core tool list, not behind a feature: any shop with products can use them, and a feature switch would hide the tools from an agent setting up its first picture. Their descriptions are kept to a line each to limit the cost to every connection.