← API Index

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:

  1. 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).
  2. Component attribute — data-<switch> on the component element: <div id="oo-cart" data-oo-shop-page="shop.html">
  3. 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).
  4. Document configuration — data-<switch> on any <script> tag of the page.
  5. 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.

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:

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:

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:

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

Ideas