@applica-software-guru/3magic-web-plugin

v1.0.7

Published

2 months ago

This plugin provides a way to integrate 3Magic's configurator in third party web applications.

Downloads

0High
0Medium
0Low

Three Magic Web Plugin

This plugin provides a way to integrate 3Magic's configurator in third party web applications.

Installation

To install this plugin using npm, run the following command in your terminal:

npm install @applica-software-guru/3magic-web-plugin

Usage

First, import ThreeMagicWebPlugin and create a new instance with the correct initialization options, structured as follows:

apiKey (string): API key authentication string. Required.
baseUrl (url string): The base URL where the 3Magic installation is running. This URL is used as the root endpoint for all API requests and interactions with the 3Magic system. Required.
domElement (HTMLIFrameElement): The iFrame instance where 3Magic will be loaded. If not provided, a new one will be generated.
lang: Specifies the language in which the plugin will operate (e.g., "en", "fr", etc.). Required.

const instance = new ThreeMagicWebPlugin({
  apiKey: 'mySecretApiKey',
  baseUrl: 'http://3magic-instance.com',
  lang: 'en'
});

Then, init the plugin:

instance
  .init()
  .then(() => console.log('ThreeMagicWebPlugin intialized!'))
  .catch((e) => console.error(e));

Lastly, start the configurator by calling load with the correct loading options:

instance
  .load({
    mode: 'family',
    payload: '7d2f638fd40df90be7b79c65'
  })
  .then(() => console.log('ThreeMagicWebPlugin loaded!'))
  .catch((e) => console.error(e));

Full example

The following is a barebone complete usage example:

<!doctype html>
<style>
  html,
  body {
    margin: 0;
    height: 100%;
    overflow: hidden;
  }
  .wrapper {
    width: 100%;
    height: 100%;
  }
  .wrapper iframe {
    width: 100%;
    height: 100%;
    border: none;
  }
</style>
<script src="dist/bundle.umd.js"></script>
<script>
  window.onload = function () {
    const domElement = document.getElementById('iframe-instance'),
      instance = new threeMagicWebPlugin.ThreeMagicWebPlugin({
        apiKey: 'mySecretApiKey',
        baseUrl: 'myBaseUrl',
        domElement: domElement,
        lang: 'en'
      });
    instance.init().then(() =>
      instance.load({
        mode: threeMagicWebPlugin.ThreeMagicWebPluginLoadingModes.FAMILY,
        payload: '7d2f638fd40df90be7b79c65'
      })
    );
  };
</script>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>3Magic Web Plugin Example</title>
  </head>
  <body>
    <div class="wrapper">
      <iframe id="iframe-instance"></iframe>
    </div>
  </body>
</html>

Loading modes

There are three loading modes supported.

3Magic family

Requires a 3Magic family ID and initializes the configurator with an empty composition.

instance
  .load({
    mode: 'family',
    payload: '7d2f638fd40df90be7b79c65'
  })
  .then(() => console.log('ThreeMagicWebPlugin loaded!'))
  .catch((e) => console.error(e));

3Magic preset

Requires a 3Magic preset ID and initializes the configurator with the corresponding preset.

instance
  .load({
    mode: 'preset',
    payload: '8a4c739be51ef01ca8d84f76'
  })
  .then(() => console.log('ThreeMagicWebPlugin loaded!'))
  .catch((e) => console.error(e));

Custom loading options

Used for custom installations. Payload will differ depending on customer specific logics and flows.

instance
  .load({
    mode: 'custom',
    payload: {
      catalog: 'CAT01'
    }
  })
  .then(() => console.log('ThreeMagicWebPlugin loaded!'))
  .catch((e) => console.error(e));

Properties

domElement (HTMLIFrameElement)

Contains the iFrame element used to display the configurator.

error (boolean)

Indicates wether the configurator is in an error state or not.

initialized (boolean)

Indicates wether the plugin has been initialized or not. Required before the loading methods can be called.

Methods

dispose(): void

Disposes of the plugin and removes all associated listeners.

init(): Promise<void>

Initializes the plugin. Returns a promise that fulfills when the initialization is complete.

initSync(onSuccess?: () => void, onError?: () => void): void

Callback version of init. Can be passed optional onSuccess and onError callbacks, that will be called once the initialization completes or fails respectively. Note, the method will return as soon as the initialization process begins.

load(options: object): Promise<void>

Loads a family or preset. Requires an options object, structured as detailed in Loading modes.

Return a promise that fulfills when the loading is complete.

loadSync(options: object, onSuccess?: () => void, onError?: () => void): void

Callback version of load. Can be passed optional onSuccess and onError callbacks, that will be called once the initialization completes or fails respectively. Note, the method will return as soon as the loading process begins.

on(event: string, listener: Function): void

Registers a listener for the specified event. See Events for a list of available events. Upon event emission, all listeners will be passed the triggering event as first arguments, plus other optional arguments depending on the event type.

off(event: string, listener?: Function): void

Unregisters a listener for the specified event. If no listener function is passed, all listeners for the provided event will be removed. See Events for a list of available events.

Events

The plugin exposes several events that can be subscribed to using the on method. These are usually utilized to intercept events that are not a consequence of direct programmatic calls to the plugin instance (e.g. an error during configurator usage). However, regular events for programmatic actions are also provided for event based programming approaches.

error

Is invoked whenever the plugin or the instanced configurator trigger an error. Each listener is passed the error object or cause.

authorizing

Invoked when the plugin commences the authorization process.

authorized

Invoked when the authorization process is successfully completed.

loading

Invoked when the plugin commences the loading process.

loaded

Invoked when the loading process is successfully completed.

custom

Used for custom installations. Each listener is passed an object containing a type string and a payload of varying type.