The BitFacet snippet

Outputs the whole filter: the form with value groups and ranges, sorting, search, products, pages and "Show more". Call it uncached.

[[!BitFacet?
    &set=`auto`
    &limit=`24`
    &tplItem=`myProductCard`
]]
ParameterDefaultWhat it does
&setexampleSet name. auto — the first set whose Sections contain the page or its ancestor (a set without sections fits any page). A comma-separated list — choose among these sets.
&parentscurrent pageComma-separated sections whose products are shown. Default — the page itself if it is a catalog section; otherwise the whole set.
&facetsallWhich filters to show and in what order: ms:vendor,ms:color.
&rangesallWhich ranges to show: ms:price.
&limit12Products per page (up to 100).
&categories1The Categories group — section tree as links. 0 — hide.
&sectionKeysectionName of the section-tree facet in the set.
&tplForm … &tplCategorybitfacet.example.*Layout chunks — table below.

Chunks and placeholders

Copy an example chunk, rename it and pass it in the parameter. Placeholder values are already escaped.

ParameterWhat it isPlaceholders
&tplFormthe whole formgroups, sorts, items, pages, more, total, q (search text), search (1 — search enabled), action, reset (URL without filters), ms (query time), endpoint, fallback, ctx
&tplGroupvalue groupkey, caption, values, open (open or empty), source, field
&tplValuevalue (checkbox)name, value, label, count, checked, disabled
&tplRangerangekey, caption, name_from, name_to, from, to, min, max, step, type (number/date), open
&tplOptionsorting optionvalue, label, selected
&tplItemproduct cardid, url, pagetitle, longtitle, introtext, uri, photo (card picture); with MiniShop3 also article, price, old_price (empty unless greater than the price), image, thumb, ms3_*; with Gallery3x — g3x_* (see "Product images" below)
&tplPagepage linkpage, url, current, class (bitfacet-page-first / -last)
&tplMore"Show more"url, page, next (how many will be added), rest (how many are left)
&tplCategoryCategories linkurl, label, count, level, current, class (bitfacet-category-root / -open / -active)
Speed. A chunk with only [[+name]] placeholders and [[%key]] lexicon strings is filled by simple substitution — fast, and turbo mode supports it. A chunk with output filters, snippets or Fenom goes through the parser (pdoTools if installed) — it works but is slower; in turbo mode such requests are served by the regular endpoint.

Example: your own product card

Chunk myProductCard with simple placeholders:

The same chunk can be written in Fenom (pdoTools required) — for example, to show a sale badge. Such a chunk goes through the parser, so it is a bit slower:

{$pagetitle}
{$price}{if $old_price} {$old_price} Sale{/if}

Product images: MiniShop3 gallery and Gallery3x

The filter takes product images from the installed galleries itself — one query per page, no snippets in the card. Only the gallery table must exist on the site; nothing to configure.

PlaceholderWhat it is
photoCard picture from whatever exists: MiniShop3 gallery (small size, otherwise thumb), otherwise the first Gallery3x image (medium), otherwise the MiniShop3 placeholder (ms3_product_thumbnail_default). Empty for plain resources without galleries.
image, thumbMain MiniShop3 product image and its thumbnail — product fields. A product without an image gets the MiniShop3 placeholder in thumb.
ms3_thumb, ms3_small, ms3_medium, ms3_largeAll sizes of the main image from the MiniShop3 gallery. Names follow the size folders in the MiniShop3 media source settings (thumbnails): a custom size card gives ms3_card.
g3x_urlOriginal of the resource's first active Gallery3x image.
g3x_small, g3x_medium, g3x_bigGallery3x thumbnails — the sizes Gallery3x creates (custom sizes — g3x_<name>).
g3x_alt, g3x_nameImage alt (the name if alt is empty), name.
g3x_countHow many Gallery3x images the resource has.

A card with a picture from any gallery — photo is enough (this is how the bitfacet.example.item chunk does it):

MiniShop3 gallery, responsive image:

[[+pagetitle]]

A catalog of plain resources with Gallery3x (no MiniShop3) — the original opens on click (data-fancybox — if the Fancybox library is on the site):

Without an image the placeholder is empty. Hide an empty image with CSS: img[src=""] { display: none; }. All placeholders are simple — the card stays fast and works in turbo mode. For the whole product gallery (several images, a slider) use the galleries' own snippets on the product page (msGallery, Gallery3x).

No page reloads (bitfacet.js)

Include one script and the filter answers without reloading the page:

What the script needs in your chunks:

the wrapper — required<form class="bitfacet" data-endpoint="[[+endpoint]]" data-fallback="[[+fallback]]" data-ctx="[[+ctx]]">
on page links and "Reset"data-bitfacet-link
on the "Show more" linkdata-bitfacet-more
search and sorting<input name="search">, <select name="sort">
where "Show more" appends products and updates pages.bitfacet-items, .bitfacet-pages

While a request is running, the form has the bitfacet-loading class — handy for a loading indicator.

Filter URLs

With friendly URLs and a catalog URL ending with "/" the filter is written into the path:

/catalog/                                         catalog
/catalog/brand-nike/                              one filter
/catalog/color-white,blue/brand-nike/             several values — comma-separated
/catalog/price-1000-5000/                         range; price-1000- and price--5000 — one side only
/catalog/instock-yes/                             yes/no
/catalog/color-white/sort-price-desc/page-2/      sorting and page — last
/catalog/brand-nike/?search=jacket                search — always a parameter

Categories and sections

The Categories group is the catalog tree as links: the current branch is expanded, the current section highlighted, each section shows its product count with the selected filters. A click opens the section page with the same filter: /catalog/clothes/color-white/.

Subsection pages need the same template (with the BitFacetSeo and BitFacet snippets) — then &set=`auto` finds the set through the ancestor.

Several contexts and languages

A set may cover several contexts (resources.contexts). The filter, product links and lexicon strings follow the context of the page with the snippet.