Helpers

Build store URLs, format money and numbers, and check the browser with the SDK's helper functions.

Read this when browser code needs a store URL, a formatted price, or a quick check of where the page runs.

The SDK ships small helpers on Salla.url, Salla.money and Salla.helpers. In React components, prefer the engine's own tools first: Link for links, useMoney for prices, and Image for images.

URLs

HelperReturns
Salla.url.get(path)The full store URL for a path: Salla.url.get('cart') gives https://store.com/cart.
Salla.url.api(path)The full URL of a store API endpoint.
Salla.url.cdn(path, width?, height?)A file on Salla's CDN, resized when you pass a width or height.
Salla.url.asset(path)A file from the theme's assets, using the asset path the store sends.
Salla.url.is_page(slug)true when the current page has that slug, such as 'cart' or 'product.single'.
Salla.url.addParamToUrl(key, value, url?)url (or the current address) with ?key=value added or replaced.

A full URL (starting with http:// or https://) is returned as it is by get, asset and cdn.

if (Salla.url.is_page('product.single')) {
  const share = Salla.url.addParamToUrl('ref', 'share');
}

For files of your own theme, import them in your code or put them in public/. See Project structure.

Money

Salla.money(amount) formats an amount in the customer's chosen currency:

Salla.money(100);                              // '100 ر.س'
Salla.money({ amount: 100, currency: 'USD' }); // 100 with the store's USD symbol

The amount comes first, then the currency symbol. When the store shows Arabic digits, the digits are Arabic.

When the store uses the new Saudi riyal symbol, Salla.money returns HTML: the symbol is an <i class=sicon-sar></i> icon. Do not put that string into React as text. In components, use useMoney.

Numbers

Salla.helpers.number(value) returns the number as a string with Arabic digits when the store has Arabic digits turned on, and with Western digits otherwise. Pass true as the second argument to always get Western digits.

Salla.helpers.number(1500);        // '١٥٠٠' or '1500', by store setting
Salla.helpers.number('١٥٠٠', true); // '1500'

Where the page runs

HelperReturns true when
Salla.helpers.isPreview()The page is inside a frame, as in the theme editor's preview
Salla.helpers.isIframe()The same check: the page is not the top window
Salla.helpers.isWebView()The page runs inside a mobile app's web view
Salla.helpers.isIOSDevice()The device is an iPhone, iPad or iPod
Salla.helpers.isAppleDevice()The device is an Apple phone, tablet or Mac
Salla.helpers.hasApplePay()The browser can pay with Apple Pay, or supports the Payment Request API

Delay a function

Salla.helpers.debounce(fn, ms) returns a function that runs fn only after calls stop for ms milliseconds (100 by default). Handy for search-as-you-type.

Gotchas

  • These helpers read window and Salla.config. Call them in the browser only, never while rendering on the server.
  • hasApplePay() checks the browser, not the store. A store without Apple Pay still returns true on a supporting browser.
  • Salla.money with a currency the store does not have falls back to the store's first currency.
  • For links between pages, use the engine's Link instead of Salla.url.get, so navigation stays inside the app.

See also

On this page