Integrating into an existing webpage

This page describes how to integrate the DIVA Framework Web Component (<diva-framework>) into an existing website.

[WIP] Work in Progress

This documentation is currently under development. If you encounter any gaps, please contact your project manager at Crystal Design.

General Integration

This section describes the basic setup that is required for all modules.

Add required scripts

You need to load React + the DIVA bundles.

Always required

• React 18
• ReactDOM 18
• @crystaldesign/diva-core (registers <diva-framework>)

Module bundles

Additional bundles depend on the module you want to integrate. See Modules.

Required Scripts (jsDelivr):

<script crossorigin src="https://cdn.jsdelivr.net/npm/react@18/umd/react.production.min.js"></script>
<script crossorigin src="https://cdn.jsdelivr.net/npm/react-dom@18/umd/react-dom.production.min.js"></script>

<script crossorigin src="https://cdn.jsdelivr.net/npm/@crystaldesign/diva-core@<VERSION>/build/umd/diva-core.umd.min.js"></script>

Initialization

This section describes how to create and mount the <diva-framework> element.

warning

Only one instance per page is supported. Do not mount multiple <diva-framework> elements at the same time.

Render inside a parent element (default)

In this mode the component renders inside the parent element and takes the size of the parent.

1. Add a container:

<div id="diva-container" style="width: 100%; height: 600px"></div>

2. Create and append the component:

const container = document.getElementById('diva-container');

const diva = document.createElement('diva-framework');
diva.organizationId = '<YOUR_ORGANIZATION_ID>';
diva.identifier = 'COMPONENT';
diva.language = 'de';

diva.currentComponent = {
  type: 'DIVA_WEBPLANNER',
  parameters: { productId: '<PRODUCT_ID>' },
};

container.appendChild(diva);

Open in fullscreen

In this mode the module opens as an overlay in fullscreen.

To open the module in fullscreen, set these flags on currentComponent:

diva.currentComponent = {
  type: 'DIVA_WEBPLANNER',
  parameters: { productId: '<PRODUCT_ID>' },
  openInFullscreen: true,
  absoluteFullscreen: true,
};

diva.addEventListener('closeComponentInFullscreen', (data) => {
  parent.removeChild(diva);
});

Listen for closeComponentInFullscreen and remove the component from the DOM when the user closes it (see Events).

Web Component properties

Name	Type	Example	Description	Required
organizationId	string	xxxxx'	Organization identifier provided by Crystal Design	yes
identifier	string	'COMPONENT'	Identifier for the embedded instance (if needed, it will be provided by Crystal Design)	no
language	string	de	UI language (defaults to de)	no
telemetry	boolean	true	Enable/disable telemetry (if configured for your project)	no
currentComponent	object	see below	Defines which module to open and with which parameters	yes

currentComponent object

Name	Type	Example	Description	Required
type	string	'DIVA_WEBPLANNER'	Which module to open	yes
parameters	Record<string, string>	{ productId: '...' }	Module-specific parameters	no
openInFullscreen	boolean	true	Open in fullscreen	no
absoluteFullscreen	boolean	true	Fullscreen uses absolute positioning (should always be activated in combination with openInFullscreen)	no

Events

This section describes how events work in general. For module-specific events, see Modules.

Listening for events

Events are emitted as CustomEvents on the <diva-framework> element.

diva.addEventListener('eventName', (event) => {
  console.log('eventName', event.detail);
});

In most cases, event.detail contains the Configuration Object (e.g. for add-to-basket or save events).
See: The Configuration Object.

Sending events

You can send events into the component with:

diva.invokeEvent('eventName');

Important events (general)

• closeComponentInFullscreen: called when the user closes the fullscreen component. In this case the webshop should remove the component from the DOM.
• onError: called if an error occurs in DIVA.

Call to Actions

We add different CTA Buttons into the modules, for example the addToCard- or Save-CTA, that trigger the standard events. It is also possible to add custom CTAs with custom events.

For module-specific CTA events, see Modules.

Modules

This section describes the module-specific bundles and the module-specific currentComponent configuration.

Configurator

The configurator is provided by the Web Planner module.

Required bundles

<script
  crossorigin
  src="https://cdn.jsdelivr.net/npm/@crystaldesign/diva-web-planner-react@<VERSION>/build/umd/diva-web-planner-react.umd.min.js"
></script>
<script crossorigin src="https://cdn.jsdelivr.net/npm/@crystaldesign/real-time-viewer@<VERSION>/build/umd/real-time-viewer.umd.min.js"></script>

Module Events

Event Name	Direction	Description
onAddToBasket	received	Triggered when a configuration should be added to the basket (see event.detail)
onWebPlanerSave	received	Triggered when a configuration should be saved (e.g. wishlist) (see event.detail)
addToBasket	sent	Sends a request to trigger the addToBasket flow (e.g. by an external button)

For the fields inside event.detail, see: The Configuration Object.

Start with an existing divaNr

Use this when a user wants to reopen an existing saved configuration.

diva.currentComponent = {
  type: 'DIVA_WEBPLANNER',
  parameters: { divaNr: '<DIVA_NR>' },
};

Start with a product

Use this to start a new configuration from a product reference.

diva.currentComponent = {
  type: 'DIVA_WEBPLANNER',
  parameters: { customProductId: '<CUSTOM_PRODUCT_ID>' },
};

PDP

The PDP module renders a product detail page component.

Required bundles

<script crossorigin src="https://cdn.jsdelivr.net/npm/@crystaldesign/product-detail-page@<VERSION>/build/umd/product-detail-page.umd.min.js"></script>

Module Events

Event Name	Direction	Description
openConfiguratorOverlay	sent	Request to open the configurator overlay from the PDP module
closeConfiguratorOverlay	sent	Request to close the configurator overlay from the PDP module

Open the PDP for a Product

diva.currentComponent = {
  type: 'PRODUCTDETAILPAGE',
  parameters: { id: '<PRODUCT_ID>' },
};