← API Index · How to use components
shop component #oo-shop
Main shop component. Most work around item selection happens here.
- renders entity lists as well as individual items, item assortments (like abo boxes) or recipes
- all items can be selected for the cart (unless something prohibits that); the selection controls are tailored to the item
- manages the browser's page history; any navigation path handed over in the URL (hash or query parameter, see
oo-qpnav) is decomposed to display the desired navigation level - optional paging for very long lists, optional "jump to top" button
One page can have only one shop component. While it is possible to have several pages with such a component, it is not recommended.
How components are mounted, how switch values are resolved and how debug output is enabled is described in the use-js-components skill.
<div id="oo-navi"></div>
<div id="oo-shop" data-oo-shop-page="shop.html" data-oo-shop-paging="40"></div>
component switches
Navigation and pages
| Switch | Default | Description |
|---|---|---|
oo-shop-page |
– | The page hosting this component. Used to build links to navigation levels (e.g. from other pages and for the history). |
oo-shop-startnav |
– | Initial navigation level as <entity>:<id> (e.g. Group:12) when the page is hit without a previous navigation. If not set, the shop's configured start category applies. |
oo-shop-omit-group |
false |
true jumps into the first group level below the addressed navigation level, so root nodes don't show up. Relevant only for calls through links (hash / query parameter). |
oo-qpnav |
true |
true hands the navigation level over as a query parameter; false appends it to the URL path instead (needs a rewrite setup on the web server). Formerly oo-hashurls. |
oo-shop-titleprefix |
– | Extra prefix for the document title, which is otherwise only the name of the object in the current navigation level. |
oo-shop-titlesuffix |
– | Extra suffix for the document title. |
List rendering
| Switch | Default | Description |
|---|---|---|
oo-shop-onlysubnavi |
false |
true: items are not shown if the level already lists elements pointing to other levels (sub navigation only). |
oo-shop-onlyitems |
false |
true: only items are shown, no sub navigation. Using it together with oo-shop-onlysubnavi makes no sense; it is ignored in that case. |
oo-shop-paging |
50 |
Paging limit. If a navigation level has more items, the pane offers a paging option. Primarily to cover extremely long listings (better avoided in the warehouse already). 0 disables paging — one potentially very long list is the result. Paging is also off with oo-shop-onlysubnavi. |
oo-shop-autopaging |
true |
true loads the next page automatically while scrolling; false shows a "more" handle instead. |
oo-shop-items-list-siblings |
3 |
When a level lists more than five items, this many items of the parent level are appended as "siblings" below the list. 0 switches that off. Not applied for single items, assortments, search results and orders. |
oo-shop-renderabopointer |
– | true: pointer items of type AssortmentGroup render the assortment group in place instead of showing a link item — an alternative way of placing the box offers. |
oo-shop-abopreview |
false |
true enables a one-click preview of an assortment's content in the assortment type list. |
oo-shop-quickabo |
true |
false removes the small subscription variant selector from the assortment list display. |
oo-shop-jumptotop |
false |
true shows a "jump to top" button (#oo-jump-to-top) once the page is scrolled down more than 300px. |
Images
| Switch | Default | Description |
|---|---|---|
oo-item-image-pi-size |
0 |
Image processing size for the small image (typically list views). A single pixel value requests a square image of that size; <w>,<h>[,<bg>] requests width, height and an optional background colour (6 hex chars). 0 requests the unscaled image. Scaling drastically reduces the transferred bytes. |
oo-item-image-pi-size-big |
0 |
Same for the big detail image of products. |
oo-item-image-pi-size-ptr |
0 |
Same for the image of pointer items (usually shown in lists). |
oo-shop-item-image-thumb |
false |
Items use the big image in list display by default (historical). true uses the small image instead, which improves loading time. |
oo-shop-zoom-titleimg |
false |
true enables the automatic zoom on title images and big detail images (kicks in only if the image is much bigger than its screen area). |
Scrolling
| Switch | Default | Description |
|---|---|---|
oo-shop-scrolltop |
– | Where to scroll when the content changes: the id of an element (without #) to scroll to, a vertical pixel position, or disable to switch scrolling on content changes off. Default is scrolling to the top. |
oo-shop-scrollshift |
– | Id of an element (e.g. a sticky header) whose height is considered when calculating the scroll position of oo-shop-scrolltop. |
Pick mode
If any of the oo-pick-* switches is set, the item selection turns into a simpler form and a click on "buy" leaves the page.
| Switch | Default | Description |
|---|---|---|
oo-pick-page-anon |
– | Page to go to after "buy" if the user is anonymous (includes located). |
oo-pick-page-auth |
– | Page to go to after "buy" if the user is authenticated. |
oo-pick-subperiod |
– | Default of the subscription period selector: none removes the whole selector, a single integer preselects that period (e.g. 2 = every 2 weeks), a /-separated list of integers (0..4) restricts the available options with the first one as default. Unset offers all options. |
Design helpers
For designing list and detail views without depending on real data, the shop can render the
built-in test item. Enter these in the search component, or use them as
navigation targets (…?np=i:-1):
| Target | Description |
|---|---|
i:-1 (or test:list in the search) |
A list of ten copies of the test item. |
i:220765 (or test:item in the search, as preview) |
The test item's detail view. |
i:-2 |
A random real item. |
i:0 |
All items flagged as "special offer". |
The test item has every attribute filled; its elements carry the class oo-shop-data-testitem.
debug options
Debug scope shop (enable with data-oo-debug="true" on the element or debug:shop:<term>+, see the skill):
| Term | Description |
|---|---|
shop:all |
General debug output (init, resolved switches, rendering, add-to-cart, favourites, sorting). |
shop:e |
Events: incoming events from logon, date, filter and navigation, outgoing oo-cart-changed. |
shop:h |
Browser history: hash/path decoding, history pops, rebuilding the navigation tree from a link. |
shop:p |
Paging: page size, automatic paging, "more" clicks. |
shop:scroll |
Scroll position calculation (oo-shop-scrolltop / oo-shop-scrollshift). |
Related scope: rend:all (the shared list/item renderer).
Events
| Element | Event | Description |
|---|---|---|
#oo-shop |
oo-shop-changed |
Issued once the major part of a state change is done. Don't rely on a complete finish of rendering at this point. Other components might listen to that event too, following up with own activities. |
Events not documented here are not for public use.
CSS
Some important selectors:
| Selector | Description |
|---|---|
.oo-shop-sl-pane |
The shop rendering area within the template. |
.oo-shop-sl-pane-tpl |
Surrounds the template that gets repeated for all navigation entries. |
.oo-shop-item |
Core area of the item data (name, price, …); may be the same element as the repeated template. |
.oo-shop-item-name |
Name of the displayed entry. All entries in the navigation tree have a name. |
div.oo-shop-sl-pane-itemstart |
Inserted as soon as single items start rendering. Groups (subgroups, recipes, …) are always rendered first. |
.oo-shop-entity-<entity> |
On #oo-shop (top level) and on the repeated elements: the entity type name, e.g. Item or SubGroup. Pointer items carry a Pointer- prefix (e.g. oo-shop-data-type-Pointer-Navi); recipe items are of type Recipe. |
.oo-shop-data-type-<type>, .oo-shop-data-<entity>-<id> |
Type and id of the rendered entry, e.g. oo-shop-data-type-AssortmentGroup oo-shop-data-AssortmentGroup-4 — use it for type- or item-specific designs. |
.oo-shop-data-type-NoItem |
The entry is not a grouping item. |
.oo-shop-item.oo-shop-item-incart, .oo-shop-item-loaded |
The item is already in the cart; the second class can carry an icon. |
.oo-shop-item.oo-shop-item-insub, .oo-shop-sub-loaded |
The item is in a subscription; the second class can carry an icon. |
.oo-shop-node-inactive |
The item is currently not available for ordering (shown e.g. because it is in an old order). |
Selectors set on the <html> element before oo-shop-changed is triggered:
| Selector | Description |
|---|---|
html.oo-page-data-type-<entity> |
Type of the navigation level entity. |
html.oo-page-data-type-NoItem |
This navigation level is not a single item. |
html.oo-page-data-<entity>-<id> |
Id of the navigation level entity. |
html.oo-shop-entity-<entity>.oo-shop-<entity>-<id> |
Same information in the older naming. |
Tips
Order of the blocks in item detail view. Default is all horizontal, floating. Force all vertical by removing (or setting to block):
.oo-shop-singleitem-info, .oo-shop-singleitem-select, .oo-shop-singleitem-img, .oo-shop-singleitem-container {
display: inline-block;
}
Image left, info and controls right:
.oo-shop-singleitem-img, .oo-shop-singleitem-container {
display: inline-block;
}
Multiple occurrence of labels. Some placeholders are shown in several locations (e.g. .oo-shop-tags). Display or hide them as appropriate.