@retail.red/storefront-library v3.3.1

retail.red Storefront Library

This library enables merchants to easily offer click & reserve functionality to their existing ecommerce website. The script can add a “reserve” button to the product detail page, via which a new reservation can be placed.

Quick Integration

To include our scripts and all its dependencies you need to add the following snippet to your shops core template. It's recommended to place it next to your other JavaScript dependencies.

<script type='text/javascript' src='https://cdn.retail.red/omni/retailred-storefront-library-v3.js'></script>

The next step is to execute the retail.red script with your own config. This needs to be executed after the product page has been completely rendered. For static pages its enough to put the following snippet at the end of your HTML page. If you are unsure when the product page is completely rendered you can use the browser load event.

<script type="text/javascript">
  window.addEventListener('load', function () {
    var retailred = window.RetailRedStorefront.create({
      apiKey: "your_api_key",
      product: {
        code: 'TEST-01',
        name: 'My test product',
        quantity: 1,
        imageUrl: 'https://url.to.product/img.png',
        price: 12.0,
        currencyCode: 'EUR',
      },
    });
    retailred.renderReserveButton('#rr-dropin');
  });
</script>

As a last step you need to define the place where the reservation button should be rendered at. For this all you need to do is place the following snippet in your product page HTML. It's recommended to place this right next to the original add to cart button.

<div id="rr-dropin" />

Example Integration

See src/dev/index.html for a basic integration example or visit the demo page.

Interface

Instance

After creating your retail.red instance with window.RetailRedStorefront.create you have the following available functions.

Custom Styling

All of the rendered UI are using CSS classes that can be used to override any styling like colors, spacings and fonts. To avoid the need of !important statements you can simply override all of the styling using the prefix "#rr-omni #rr-omni-custom". This will ensure that your custom styling outweighs the defaults. For a button for example simply use

#rr-omni #rr-omni-custom .rr-button {
  margin: 8px;
  ...
}

For colors we provided CSS variables that can be overridden once for all usages.

#rr-omni #rr-omni-custom, #rr-omni-reserve-button, #rr-inventory-custom {
  /* Color for common text. If not set, the primary page color will be used */
  --rr-color-text: inherit;
  /* Color for text with a medium emphasis */
  --rr-color-text-medium-emphasis: #666666;
  /* Primary color used for form elements and reserve buttons */
  --rr-color-primary: #000;
  /* Contrast color for the primary color - used as button text color  */
  --rr-color-primary-contrast: #fff;
  /* Secondary color used for search buttons, variant selection and form elements. Falls back to --rr-color-primary when not set */
  --rr-color-secondary: var(--rr-color-primary);
  /* Contrast color for the secondary color - used as button text color. Falls back to --rr-color-primary-contrast when not set.  */
  --rr-color-secondary-contrast: var(--rr-color-primary-contrast);
  /* Color used for links */
  --rr-color-link: #3c9bb5;
  /* Text color for disabled buttons */
  --rr-color-button-disabled: #7f7f7f;
  /* Background color for disabled buttons */
  --rr-color-button-background-disabled: #E0E0E0;
  /* Color used for alerting texts like errors */
  --rr-color-status-alarm : #b00020;
  /* Color used for highlighting problems like low stock */
  --rr-color-status-warning: #f19c45;
  /* Color used for positive highlighting like successful reservation text */
  --rr-color-status-success: #32ac5c;
  /* Font family for the modal */
  --rr-font-family: inherit
}

Configuration

The following configurations can be specified during initialization in the RetailRedEnablement.create method. Or at any time later before the reserve button is rendered using:

retailred.updateConfig({
  customer: {
    firstName: 'Max',
  },
});

Core Configuration

Product Configuration

Customer Configuration

These will be used to prefill the reservation form with the currently logged in user.

Inventory Configuration

Localization Configuration

{
  ...
  localization: {
    de: { 'reserve.submit': 'Reserve JETZT' },
    en: { 'reserve.submit': 'Reserve NOW' },
  }
}

Special Strings

Besides the strings which are available via the locale files, there are some where the storefront library doesn't provide default translations.

Legal Configuration

Newsletter Opt-In Configuration

UI Configuration

{
  ...,
  ui: {
    reserveButtonClasses: 'my-custom-button button-primary'
  }
}

Hooks Configuration

The Storefront Library provides hooks that can be used to intercept default logic and modify existing, or inject custom data. Hooks are async functions that should return a Promise that resolves with the result.

afterCreateStoreListLocations

This hook can be used to modify the location data before it's rendered inside the store list template.

{
  ...,
  hooks: {
    afterCreateStoreListLocations: function (locations, product, { t, sdk }) {
      return new Promise(function (resolve) {
        // Dispatch additional requests... modify locations data... resolve with the updated location data
        resolve(locations);
      })
    }
  }
}

Custom Templates

If styling and configuration is not enough for your needs you can always completely override the default templates. Following templates can be overridden:

A custom template can be added directly to your html

<template id="custom-template">
  This is my custom template
  <script>
    console.warn("Hello World")
  </script>
</template>

<script type="text/javascript">
  retailred.updateConfig({
    templates: {
      customTemplates: {
        success: document.querySelector('#custom-template').innerHTML,
      }
    },
  })
</script>

or by loading it from an external file. Be aware that CORS rules apply.

<script type="text/javascript">
  xhr = new XMLHttpRequest();
  xhr.onreadystatechange = handleStateChange;
  xhr.open("GET", "/my-template.hbs", true);
  xhr.send();

  function handleStateChange() {
    if (xhr.readyState === 4 && xhr.status === 200) {
      retailred.updateConfig({
        templates: {
          customTemplates: {
            success: xhr.responseText,
          },
        },
      })
    }
  }
</script>

If your template needs access to custom variables:

retailred.updateConfig({
  templates: {
    customVariables: {
      myVariable: '1234',
    },
  },
});

If your template needs further helpers you can also add those:

window.RetailRedStorefront.registerTemplateHelper('my-helper', function (name) { return 'Hello ' + name });

and use them like any other helper

<div>
  {{my-helper "World"}}
</div>

API Client SDK

Additionally to the enablement UI script we also provide a client sdk for the storefront api. The methods are all async and therefore return a Promise that holds the result.

var sdk = new window.RetailRedStorefrontSdk('my-api-key');
sdk.getLocations({ countryCode: 'de', postalCode: '35510' }).then(function(result) {
  console.log("Result:", result);
});

Development

Requirements

• NPM >= LTS
• Node.js >= LTS

To execute the project in development mode simply execute the following lines in the terminal.

npm i
npm start

This wil by default host the test site at http://localhost:8080

Support

If you have any questions or feedback, please contact us at mail@retail.red

License

This product is available under the Apache License, Version 2.0. See the LICENSE.md file for more information.