Skip to content

Product Views

A product's variants are whole products, each with its own linked images. A shirt in 25 sizes and colours, with three photos per variant, makes Mongo resolve about 75 image records every time the shirt is mapped. A page that shows a name, a price and a picture should not pay for that, so reads that show only part of a product ask for a view.

The views

ProductView (in common, package catalogue) names how much of a product a read loads. The field lists live in one place, ProductViews, and only ProductRepositoryImpl applies them.

View Leaves out For
REF everything but id, catalogueId, skuId, seoName, productName, disabled pickers, resolving names and ids
CARD description, variants thumbnails and cards that never ask about options
LISTING description, the variants' images and descriptions search, category and collection grids
LINES description, and every variant not on the order (the rest keep their images) basket and order lines
FULL nothing product pages, admin edits, anything that saves

A CARD product has no variants, so a listing card would show "Add to basket" on a product that has sizes. Grids read LISTING: the variants are there for "Choose options", "From" prices and the shared sale price and the colours a card's swatches list, without the images that make them expensive. A swatch's picture is fetched when the shopper first points at it, from the gallery endpoint (GET /api/public/v1/products/{seoName}/gallery?variant=), which reads the product whole.

Asking for a view

ProductService methods that take a ProductView:

  • findAllByIdInAndSite(ids, view, siteContext): search and category hydration.
  • findListableBySiteAndCollectionIDs(siteContext, seoName, endedBefore, pageable, view): collection listings. Cached in productLists under its own key, which carries the view.
  • findLinesBySkus(siteContext, productSkus, variantSkus): LINES, for a basket or an order (DisplayTools.constructDisplayOrder).
  • findCardsBySkuIdInAndSite(skuIds, siteContext) and findCardsByIdInAndSite(ids, siteContext): CARD, for an order's thumbnails and the related-products rail (whose cards show no options).

The methods without a view still read FULL, so nothing changes until a caller opts in.

Storefront search and category pages put .productView(ProductView.LISTING) on their SearchQuerySpec. While a filter is selected, MerchandisingQueryService reads those hits FULL anyway: a colour-filtered card shows the matching variant's own pictures (ListingImages), and LISTING leaves variant images out. The REST search and anything else that doesn't ask stays FULL.

A partial product can't be saved

Every product a partial read returns carries Product.loadedAs (null for a whole product). The marker isn't stored in Mongo but survives the Redis caches, so a product read back from productLists is still marked.

PartialProductSaveGuard, a Mongo mapping-event listener, throws PartialProductWriteException when a marked product reaches a save or insert from any app. Saving it would replace the stored document with the partial copy and wipe the variants or description. To change a product, read it FULL. Targeted updates (updateFirst of named fields) write only what they name and aren't checked.

Templates

A template that reads a field the view left out gets null, not an error. Before moving a page to a view, check what its templates read. The listing cards read miniDescription (not description) and the product's own images (not the variants'), which LISTING keeps.

Keeping it that way

  • ProductFullReadRatchetTest (web-mvc) counts the calls to whole-product list finders (findAllByIdInAndSite, findListableBySiteAndCollectionIDs, findBySiteAndCollectionIDs, findByCatalogueIDAndSkuIdOrVariantsSkuId, findBySite, quickSearch, findByReferences) that pass no ProductView, per file, in the web-mvc sources, commerce-core's extensions and render packages, the MCP tools and the REST API. A new one fails the build. When a count drops, lower product-full-read-baseline.properties (test resources).
  • The badger.products.mapped counter (ProductMappingCounter) counts every product mapped from Mongo, tagged with the view it was read as. A rise in view=FULL after a release points at a page that started reading whole products to show a few fields.