Programmatic access (Mobius)

This article is for people who can write JavaScript. If links and buttons are enough for you, stay with the data-mobius attribute from Getting started: it covers almost everything.

Programmatic access works in blocks on the home screen, the product card and in stories. It is not available in articles, news items or static pages: use ordinary links and buttons there.

The Mobius object

Inside a block, the global Mobius object is available. Through it any command can be called and its result received:

<button onclick="Mobius.basket.add('15', 2)">Add 2</button>

Every command returns a promise, so you can wait for the answer and react to it:

<button id="buy">Buy</button>

<script>
  document.getElementById('buy').addEventListener('click', async () => {
    const result = await Mobius.basket.add('15', 1);
    if (result.ok) {
      Mobius.notification.toast({ title: 'Added', message: 'The product is in the basket' });
    }
  });
</script>

Command names are the same as in the reference: the dot in a name becomes a property lookup. basket.add becomes Mobius.basket.add(...), catalog.openProduct becomes Mobius.catalog.openProduct(...).

Data about the user and the app

As soon as the block loads, the Mobius.context object is available, a snapshot of the current state:

An example, greeting by name:

<p id="hello"></p>

<script>
  const name = Mobius.context.user ? Mobius.context.user.name : 'guest';
  document.getElementById('hello').textContent = 'Hello, ' + name + '!';
</script>

Reacting to changes

A block can update itself when something changes in the app. Subscribe to an event with Mobius.on:

<p>Items in the basket: <b id="count">0</b></p>

<script>
  Mobius.on('basket:changed', data => {
    document.getElementById('count').textContent = data.basketCount;
  });
</script>

Useful details

• Mobius.invoke('basket.add', { id: '15', qty: 1 }) calls a command by its full name. Handy when the command name is built from a variable.
• Mobius.has('basket.add') checks whether a command is supported in this app version. It helps build blocks that do not break on older versions.
• Mobius.version gives the bridge version.

Handling errors

If a command fails (a required parameter was missing, say), the promise rejects. Wrap such calls in try / catch:

<script>
  async function setRegion() {
    try {
      await Mobius.region.set({ id: '77', title: 'London' });
      Mobius.notification.toast({ title: 'Region changed' });
    } catch (e) {
      Mobius.notification.toast({ title: 'Could not change it', type: 'error' });
    }
  }
</script>

What next

• Command reference: the full list of commands.
• Examples: ready blocks, including one with a live basket counter.