Carousel extension

The horizontal carousel layout renders each category as a swipeable row. It is the most dynamic of the archive layouts and the one with the most integration surface, because rows are initialised, updated and re-synchronised as content arrives.

What the layout produces

• One carousel per category term, rendered inside the archive's results container.
• A category navigation that moves between rows.
• Progressive loading of further items into an existing row.

Split-by-term archives render an independent carousel per term rather than one host carousel containing everything.

Behaviors an extension must respect

Carousels stay initialised across result updates. Archives can update their results through several paths — classic rendering, progressive loading, pagination, infinite scroll, a load-more control, and faceted search results. A carousel must remain initialised and synchronised through all of them rather than being rebuilt each time.

Incoming items are staged, not appended raw. New items are prepared before insertion so that partially rendered content never appears below the carousel.

Loading triggers live inside the carousel. The trigger that requests the next batch is a slide within the row, so reaching the end of the row is what loads more.

DOM identity is preserved. The staging element becomes the first incoming result rather than being discarded, which avoids positional jumps during insertion.

Pagination rendering must not recurse. Recursive re-rendering of the pagination causes flicker and unstable dynamic bullets.

Implications for custom code

If you extend or replace carousel behavior:

1. Do not re-initialise on every update. Re-use the existing instance and update it.
2. Insert through the staging path, not by appending markup directly to the row.
3. Keep the trigger slide inside the carousel, or infinite loading will stop working at the row's end.
4. Do not assume a fixed slide count. Rows grow as batches arrive.
5. Leave pagination rendering alone unless you are replacing it wholesale.

Faceted results

When a faceted search is present, its result wrappers must survive the conversion of an archive into per-term carousels. An extension that rebuilds the results container from scratch will remove them.

If your integration renders results, preserve the existing wrappers rather than replacing the container.

Progressive JSON

Compatible progressive archives can request their JSON separately from the page. Where a site also runs POM Cache, that JSON has its own cache with its own invalidation controls.

Custom endpoints that return archive data should behave consistently with that model: cacheable, invalidated on content change, and independent of the HTML cache.

Testing an extension

• Load a category with more items than one batch and reach the end of the row.
• Apply an allergen filter and confirm rows re-render correctly.
• Use the category navigation to jump between rows.
• Load the archive on a phone and check swipe behavior.
• Confirm no partially rendered content appears below a row during loading.
• Confirm pagination bullets remain stable.