Category pages

A category page is a search without text on the category_page surface, naming the category. The sofa page wohnen/sofas (wohnen: living) lists four sofas:

curl -s 'http://127.0.0.1:7800/v1/search?on=category_page&category=wohnen/sofas' \
  | jq -c '.listed, (.sections[] | {type, total, hits: [.hits[].entity]})'

"product"
{"type":"product","total":4,"hits":["product:SOFA-ASKA-2","product:SOFA-LUND-3","product:SOFA-NIKO-SCHLAF","product:SOFA-VIDAR-ECK"]}

The answer holds one section, the type the page lists, with the page's facets. listed names that type: products, unless the category holds more of another type with offers, such as a workshop's services. Filters and pages work as in any search (Facets and filters).

Reference: category · listed

The category and below itCopy Anchor Link

A page lists what the catalog assigns to its category and to every category below it. wohnen lists the products of its five subcategories, and its category facet counts them:

curl -s 'http://127.0.0.1:7800/v1/search?on=category_page&category=wohnen' \
  | jq -c '.sections[] | select(.type == "product")
      | .total, (.facets[] | select(.field == "category") | .values[] | {value, label, count})'

11
{"value":"wohnen/sofas","label":"Sofas","count":4}
{"value":"wohnen/tische","label":"Tische","count":3}
{"value":"wohnen/sessel","label":"Sessel","count":2}
{"value":"wohnen/regale","label":"Regale","count":1}
{"value":"wohnen/stuehle","label":"Stühle","count":1}

The category facet is hierarchical: it lists the subcategories one level down, such as Sessel (armchairs) and Tische (tables). Choosing one, as { "category": { "within": "wohnen/sofas" } }, narrows this page. Link it to its own page instead where the shopper should get that page's own facets and banners.

Banners and teasersCopy Anchor Link

placements holds the banners rules place on the page, in the order the page draws them. Banners and teasers shows how a merchant places one:

curl -s 'http://127.0.0.1:7800/v1/search?on=category_page&category=wohnen/sofas' \
  | jq -c '.placements[] | del(.text, .image, .link)'

{"slot":"top","kind":"banner","title":"Sofas im Angebot","rule":"home/sofa-sale"}
{"slot":"grid","position":4,"kind":"teaser","title":"Sessel aus Leder, Samt und Stoff","rule":"home/sofa-sale"}

The home store's rule home/sofa-sale puts a banner on top, "Sofas im Angebot" (sofas on sale), and a teaser to the armchairs in the grid before the fourth tile. Each comes with its text, image and link in the request's locale.

A banner is not a hit: totals, facets and hits are the same without it, so paging stays as it is. A grid banner's position counts tiles across pages:

curl -s 'http://127.0.0.1:7800/v1/search?on=category_page&category=wohnen/sofas&per_page=2&page=2' \
  | jq -c '[.placements[] | {slot, position}], (.sections[] | {total, hits: [.hits[].entity]})'

[{"slot":"grid","position":4}]
{"total":4,"hits":["product:SOFA-NIKO-SCHLAF","product:SOFA-VIDAR-ECK"]}

With two tiles per page, the teaser stands before the second tile of page 2, at position - (page - 1) * per_page. A top banner comes with the first page only, a bottom one with the last. A count_only request carries none.

Reference: placements · position

Where the page starts sortingCopy Anchor Link

A page without words starts in the default sort of its category's node, the nearest up the tree, and the answer's sorts marks it. The home store's pages start by relevance, labeled "Beste Treffer" (best matches). Sorting shows how to offer the others.

An unknown categoryCopy Anchor Link

A category the catalog does not hold answers an empty product section, not an error. A storefront that serves pages by their URL learns of it earlier: resolve answers its path with not_found.

Breadcrumbs and the page's URLCopy Anchor Link

The page's path comes from the catalog, per locale, and resolve answers it with the trail above the page:

curl -s -G http://127.0.0.1:7800/v1/resolve --data-urlencode 'url=/wohnen/sofas' -d results=0 \
  | jq -c '{entity, canonical}, .breadcrumbs'

{"entity":"category:wohnen/sofas","canonical":"/wohnen/sofas"}
[{"title":"Wohnen","url":"/wohnen"},{"title":"Sofas","url":"/wohnen/sofas"}]

The same page sits at /en/living/sofas in English. Without results=0, resolve brings the page's results in the same call, so a storefront renders a category page from one request (URLs and redirects).

Reference: breadcrumbs · canonical

NextCopy Anchor Link

• Facets and filters: the facets a page answers with and how a shopper chooses.
• Sorting: the orders a page offers.
• URLs and redirects: serve every page from its own URL.