@applica-software-guru/3magic-web-plugin
v1.0.7
Published
This plugin provides a way to integrate 3Magic's configurator in third party web applications.
Downloads
78
Keywords
Readme
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-pluginUsage
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.