Use the JavaScript components
Beside the low-level API (see use-api) we offer a JavaScript toolkit that encapsulates most shop logic as components. Each component covers one topic of online shopping — the cart, the item/category display, delivery date selection, logon, profile, search, order status, … The standard shop is built from the same components, so everything the standard shop can do is available to your own page set.
A component is mounted by placing an element with the component's id into your HTML; the toolkit finds it, loads its template body (if your page does not already contain one) and wires up all behaviour. The individual components are listed under JS Components in the API index. How the toolkit gets onto your page is described in Setup.
Setup
Minimal installation
Add one script tag to the <head> of every page that should host components:
<!DOCTYPE html>
<html>
<head>
<script src="https://<server>/v3/shop/<shopname>/api/client3.js"></script>
</head>
<body>
<h1>My Shop</h1>
<div id="oo-navi"></div>
...
<div id="oo-cart" data-oo-shop-page="shop.html" data-oo-date-page="date.html"></div>
...
</body>
</html>
<server> is the host assigned to your shop (e.g. oekobox-online.de), <shopname> the
shop instance id. The script downloads the toolkit and its dependencies, binds the page to
this shop instance (all data is exchanged exclusively with it) and then processes the page:
every element whose id matches a component (oo-cart, oo-shop, …) is turned into that
component. Most components may appear only once per page (the component's doc says so).
This minimal variant is useful even together with the traditional iframed shop, e.g. to place the ticker component on your start page.
Versions
The script is developed continuously but stays backwards compatible. Incompatible changes get
a new number after client:
| Script | Status | Notes |
|---|---|---|
client3.js |
current (since January 2025) | 2025 templates for all components, embedded jQuery 3.7. Use this. |
client2.js |
deprecated (June 2020) | jQuery 3.5, fully decoupled from a page's own jQuery. |
client1.js |
deprecated (January 2018) | jQuery 3.x, private module loader. |
client.js |
obsolete | jQuery 2.x; required a conflict-free script loading order. |
Do not host a local copy of the client script in production: it would shadow the versioning information the system relies on.
Script parameters
Parameters are appended to the script URL (client3.js?config=std1&css=0):
| Parameter | Description |
|---|---|
config=<set> |
Loads a default configuration and its CSS: std1 — the standard template (2025), std1-embedded — the standard template embedded into an existing page (the regular case), plain — same settings but with the unoptimised CSS files. std / std-embedded are the older names and map to the same. Without config, only the toolkit's base CSS is injected and you design the pages yourself. |
css=0 |
Don't inject any CSS. Use it if you compile the framework CSS into your own build (sass/less/webpack); you are then responsible for keeping your copy up to date — the framework may change at any time (after short announcement). |
css=<url> |
Inject the framework's CSS just before your own stylesheet — normally after other frameworks' CSS (bootstrap etc.). |
css=1 |
Inject the standard template CSS (same as config=std1). |
noinit |
Don't initialise the components automatically; you call oo.initWeb() yourself from your init script (see below). |
jq |
Expose the built-in jQuery as window.jQuery / window.$ the traditional way, so other scripts can use it. Without it, the toolkit's jQuery is reachable only as window.oojq. |
embedid=<id> |
For the embedded standard shop: id of the page element the shop is rendered into (default oo-shop-embedded). |
raw=1 |
Skip the CSS adjustments and placeholder HTML configured in the shop's admin area — handy to see the pure template. |
nocatch=true |
Disable the built-in error catcher, which reports JavaScript errors (including those in your init script) back to the shop's support log. Use it while you trace errors yourself. |
nologin |
Initialise without the logon state check (public pages that need no customer data). |
Configuration in one place: the init script
Instead of repeating the same data- attributes on every component, put them into an
initialisation script referenced with data-main (the script is loaded through the toolkit's
module loader, so it runs once the toolkit is available):
<script data-main="app.js" src="https://<server>/v3/shop/<shopname>/api/client3.js"></script>
// app.js — hook into the bootstrap process
oor.require(["oo"], function (oo) { // oo is available here
oo.configureComponents({
"oo-shop-page": "shop.html",
"oo-cart-page": "cart.html",
"oo-logon-page": "logon.html",
"oo-profile-page": "profile.html",
"oo-date-page": "date.html",
"oo-loggedon-page": "shop.html",
"oo-loggedout-page": "index.html",
"oo-register-page": "profile.html"
});
var $ = window.oojq; // need jQuery? use the toolkit's instance
});
This example lists only page switches (as they are repeated most often), but any switch can
be provided here. All components then see the same value for a name — two tickers with a
different setup on one page still need data- attributes.
Simple cases can also go onto the script tag itself: <script data-oo-shop-page="shop.html" src="…/client3.js">.
Running code before and after initialisation
With noinit you control the initialisation yourself and can run code before and after it:
<script data-main="app.js" src="https://<server>/v3/shop/<shopname>/api/client3.js?noinit"></script>
oor.require(["oo"], function (oo) {
function appInit() {
// runs AFTER the components are initialised and the page was processed
}
// code that should run BEFORE initialisation (configureComponents, mixins, ...)
var $ = window.oojq;
oo.initWeb(appInit, false, shopid); // shopid is set implicitly by the client script
});
Without noinit, use the loading events instead:
Event (on document) |
Description |
|---|---|
oo-loaded |
The toolkit was initialised and processed the page. |
oo-embedded-loaded |
Same, for the embedded standard shop. |
window.oojq(document).on("oo-loaded", function () { /* ... */ });
You must bind with the toolkit's own jQuery instance (window.oojq) to receive these events.
Different shop pages for different navigation levels
You may design different pages for different categories. Whenever a component is about to display another navigation level it checks this map first and changes the page if needed (remember that a page change means loading the new page first):
oo.configureComponents({ "oo-shop-page": "shop.html" }); // default if no mapping fires
oo.configureShopPageMap({ // "<entity>:<id>": page — first match wins
"Group:66": "shop1.html",
"Group:68": "shop2.html"
});
All known entity types can be used.
Mixing CSS classes into the templates
To add classes of an external CSS framework to the toolkit's templates:
oo.addMixins({
".oo-navi-image-name": "h3", // bootstrap sizes
".oo-flash-msg": "alert alert-success" // bootstrap colours
});
You still need to load the framework's CSS yourself.
jQuery
jQuery is the only library the toolkit depends on, and it brings its own copy that does not
interfere with a jQuery your page may already load. Use window.oojq wherever you need the
exact instance the toolkit uses (events, plugins on component elements); add the jq
parameter if legacy scripts expect the globals jQuery / $. Running several jQuery versions
on one page is possible but not recommended.
Embedding the standard shop into an existing site
If you don't build your own page set, embed the standard design into a CMS page with two lines:
<div id="oo-shop-embedded">Shop wird geladen...</div>
<script src="https://<server>/v3/shop/<shopname>/api/client3.js?config=std1-embedded"></script>
Use embedid to render into another element. Further fine tuning is usually done with CSS
from the shop's admin area.
Component switches
Components are configured with switches: named values such as oo-shop-page or
oo-cart-long. Every component doc lists its switches with their default. Switch names are
lower case and prefixed with oo-; component-specific switches carry the component name
(oo-cart-…), general ones (oo-shop-page, oo-item-image-pi-size, …) are shared by
several components and are best set globally.
Where a switch value comes from
A switch can be provided in several places. They are checked in this order, the first value found wins:
- Ad-hoc switch — a value stored in the browser. It gets there either by typing it into the search field at runtime (see Ad-hoc switches at runtime) or centrally through the backend setting Component switch (WebShop) (see Central switches from the backend).
- Component attribute —
data-<switch>on the component element:<div id="oo-cart" data-oo-shop-page="shop.html"> - Global configuration — an object passed to
oo.configureComponents({...})from your page's script, e.g.oo.configureComponents({ "oo-shop-page": "shop.html", "oo-cartmode": "cart" }). This is the right place for switches that several components share. The standard shop configures itself this way (see below). - Document configuration —
data-<switch>on any<script>tag of the page. - The default documented for the switch. Switches without a default are simply "not set".
A value ending with ! (e.g. data-oo-cartmode="cart!") overrides all other sources
regardless of the order above; the ! itself is stripped.
Boolean switches accept true/false as well as 1/0. Numeric switches must be plain
integers — anything else falls back to the default.
Check the naming of a switch: if it carries the component name in it (like oo-profile-select), its likely only useful for this component. If not, its likely a more global option that is used by different components. Exceptions are the -page- Switches, which are mostly global.
Page links (<rel-path>)
Many switches point to another page of your page set ("page switches", e.g. oo-shop-page,
oo-date-page, oo-thankyou-page). Their value can be:
- a path relative to the current page (
shop.html,../checkout/cart.html) - a css id starting with
#(#shop) — for single-page layouts that switch between visible elements instead of loading another page - a value starting with
:— the rest is evaluated as a JavaScript expression instead of navigating, e.g.data-oo-date-page=":openDateDialog()" ?— nothing happens; use it if you attach your own click handler to the element- a value starting with
@is reserved for the embedded standard shop
Ad-hoc switches at runtime
Ad-hoc switches let you try a configuration without touching the page or the backend settings. Type into the shop's
search field (the oo-search component):
| Input | Effect |
|---|---|
oo-cart-long=5+ |
set switch oo-cart-long to 5 |
oo-cart-long? |
print the currently effective value of the switch to the browser console |
oo-clear |
remove all ad-hoc switches |
Ad-hoc switches are stored in the browser (local storage) and therefore survive reloads and
affect every page of the shop in that browser — don't forget oo-clear when you are done.
Switches are read when the component initialises, so reload the page after a change.
Central switches from the backend
If you want to change a setting for all visitors, it is best to place it into the page set as
explained above (element attribute or global configuration). If that is not possible — e.g.
the pages are not yours to edit — a shop operator can set switches for all customers
without touching any page: in the backend under Settings → Einstellungen und Optionen für Entwickler the field
Component switch (WebShop) (German: Komponenten-Schalter (WebShop)) takes a comma
separated list of switch=value entries, e.g.
oo-logonmode=email1st, oo-cart-long=10, oo-item-image-pi-size="330,330"
Quote a value that itself contains a comma. An entry without = sets the switch to an
empty value.
The client script that every shop page loads writes these entries into the browser's ad-hoc store on each page load — so they behave exactly like ad-hoc switches (level 1 above) and override element attributes and global configuration. Consequences:
- Because they are stored in the browser, removing an entry from the setting does not
remove it from browsers that already have it. Set the field to the single word
clear(and leave it there for a while) to wipe the ad-hoc store in every browser, then enter the new list. - A switch set this way also overrides values you set in the page. If a page "ignores" its
attribute, check this setting (and
oo-…?in the search field shows the effective value). - Like every backend setting it takes a few minutes to reach all servers.
The standard shop's configuration
If you use the standard shop pages (instead of your own page set), they come with a global
configuration (oo.configureComponents) that links the standard pages to each other
(oo-shop-page, oo-cart-page, oo-logon-page, oo-profile-page, oo-date-page, …) and
sets a few defaults such as oo-logonmode=email1st, oo-date-calendar=true,
oo-item-image-pi-size=330,330 and oo-item-image-pi-size-big=800,800. Use the backend
setting above to change one of them for your shop.
Debug output
Every component can print diagnostic output to the browser console. Output is organised in
scopes (usually the component name) and terms within a scope (all, render,
buttons, …); the component doc lists its terms.
Two ways to enable it:
data-oo-debug="true"on the component element enables all terms of that component.- Per term, again via the search field:
| Input | Effect |
|---|---|
debug:cart:render+ |
switch term render of scope cart on |
debug:cart:render- |
switch it off again |
debug:show |
list all enabled terms in the console |
debug:off |
disable everything |
Debug settings are stored in the browser like ad-hoc switches and are evaluated when the component initialises — reload after a change. Debug output is meant for development; it is not localised and may change between versions.
The backend setting Debug switch (WebShop) (next to the component switch setting) does
the same centrally for all customers' browsers: a comma separated list of scope:term
entries, e.g. cart:all, shop:h, or clear to wipe the stored debug settings in every
browser. Keep it empty in production — the output ends up in every customer's console and
in the remote log.
Don't forget
- Always load the client script from the shop server (
.../api/client3.js), never a local copy - versioning and fixes depend on it. - Use
config=std1-embedded(orstd1) unless you really build your own page set; then decide early whether you keep the injected CSS or compile it yourself (css=0). - Switches set on the element (
data-…) override the global configuration — handy for a single special page, confusing if you forget about it. Prefer global settings and use element attributes for exceptions. - Ad-hoc and debug settings live in the browser's local storage. If a shop "behaves
strangely" only in one browser, check for leftovers with
oo-…?/debug:show. If it behaves strangely in all browsers, check the backend's component/debug switch settings. - Backend switches are sticky: after removing an entry, set the field to
clearonce so browsers that stored the old value drop it. - Page switches are resolved relative to the current page; when you move pages into subfolders, revisit them.
- Components exchange events (e.g. the cart re-renders when the date changes). If you mount
only part of the components on a page, make sure the pages they link to (
oo-…-page) host the counterpart.
Ideas
- A minimal "quick order" page: just
oo-statusandoo-cartwithoo-cartmode="cart"and a thank-you page, for returning customers who know what they want. - Use
:-functions on page switches to open components in an overlay instead of leaving the page. - Use
data-oo-debug="true"on one component while developing its page; remove before go-live.