Configurator Widget

WIP: Work in Progress

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

The Configurator widget is the fastest way to add the DIVA Configurator to a website. You load one script and mark up an HTML element with data-diva-* attributes. No JavaScript initialization code is required.

The widget comes in two variants that differ only in how the Configurator is opened:

• Button: the fullscreen Configurator opens when a visitor clicks the element. Perfect for product detail pages, collection pages, or anywhere you want a "Configure" button.
• Direct: the fullscreen Configurator opens automatically when the page loads. Useful for a dedicated configuration page that visitors reach via a link, e.g. from a product page or a campaign.

In both cases the page is shown again when the visitor closes the Configurator. Optionally, you can react to the close and add-to-basket actions with your own JavaScript functions.

Step 1 – Add the Widget Element

Place an element on the page and select the variant with the data-diva-widget-type attribute. The product to open is given in data-diva-param-productid.

Widget type	Opens the Configurator
diva-configurator-button	when the visitor clicks the element
diva-configurator-direct	automatically when the page loads

Important

Replace <PRODUCT_ID> with the ID of the product that should be opened in the Configurator.

Button

Place the element anywhere on the page where you want customers to start configuring.

<div data-diva-widget-type="diva-configurator-button" data-diva-param-productid="<PRODUCT_ID>">
  Configure product
</div>

Style the element with your own CSS, e.g. to make it look like a button. You can change the text to "Start Configuration", "Personalize Now", etc.

Direct

The Configurator opens as soon as the widget script has loaded. The content of the element is visible once the Configurator is closed, so it can hold a short message or a link back to your shop.

<div data-diva-widget-type="diva-configurator-direct" data-diva-param-productid="<PRODUCT_ID>">
  The Configurator opens automatically
</div>

Step 2 – Load the Widget Script

Include the widget script before the closing </body> tag, after the element from Step 1.

Important

Replace <YOUR_ORGANIZATION_ID> with your organization ID.

<script src="https://api.diva-portal.com/integration/api/widget/<YOUR_ORGANIZATION_ID>"></script>

That's it. The Configurator now opens in fullscreen mode, on click or on page load depending on the widget type.

Step 3 – React to Configurator Events (optional)

The widget can call your own JavaScript functions when the visitor closes the Configurator or adds the configured product to the basket. Reference the name of a global function in the corresponding attribute and define the function before the widget script is loaded.

<div
  data-diva-widget-type="diva-configurator-button"
  data-diva-param-productid="<PRODUCT_ID>"
  data-diva-param-onclose-event="onConfiguratorClose"
  data-diva-param-onsavebasket-event="onSaveBasket"
>
  Configure product
</div>

<script>
  function onConfiguratorClose() {
    // The visitor closed the Configurator
  }
  function onSaveBasket() {
    // The visitor added the configured product to the basket
  }
</script>

For the Direct variant, the close callback is a good place to send the visitor back to where they came from, e.g. with history.back(), since the page has no other content of its own.

tip

Products may vary from page to page, as a Best Practice this should be managed dynamically. Link the data-diva-param-productid value to a user-accessible field within your CMS (like WordPress).
This allows team members to update products directly through the admin interface without ever touching the integration code.

Complete Examples

Button – full HTML page

<!doctype html>
<html>
  <head>
    <title>Configurator Button Widget</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <style>
      #configure-btn {
        display: inline-block;
        padding: 0.75rem 1.5rem;
        background-color: #713434;
        color: #fff;
        border-radius: 4px;
        cursor: pointer;
      }
    </style>
  </head>
  <body>
    <div
      id="configure-btn"
      data-diva-widget-type="diva-configurator-button"
      data-diva-param-productid="<PRODUCT_ID>"
      data-diva-param-onclose-event="onConfiguratorClose"
      data-diva-param-onsavebasket-event="onSaveBasket"
    >
      Configure product
    </div>

    <script>
      function onConfiguratorClose() {
        alert('Configurator closed');
      }
      function onSaveBasket() {
        alert('Product added to basket');
      }
    </script>

    <script src="https://api.diva-portal.com/integration/api/widget/<YOUR_ORGANIZATION_ID>"></script>
  </body>
</html>

Direct – full HTML page

<!doctype html>
<html>
  <head>
    <title>Configurator Direct Widget</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
  </head>
  <body>
    <div
      data-diva-widget-type="diva-configurator-direct"
      data-diva-param-productid="<PRODUCT_ID>"
      data-diva-param-onclose-event="onConfiguratorClose"
      data-diva-param-onsavebasket-event="onSaveBasket"
    >
      The Configurator opens automatically
    </div>

    <script>
      function onConfiguratorClose() {
        // Return to the previous page
        history.back();
      }
      function onSaveBasket() {
        alert('Product added to basket');
      }
    </script>

    <script src="https://api.diva-portal.com/integration/api/widget/<YOUR_ORGANIZATION_ID>"></script>
  </body>
</html>

Attributes

Attribute	Example	Description	Required
data-diva-widget-type	diva-configurator-button	Selects the variant: diva-configurator-button (open on click) or diva-configurator-direct (open on load)	yes
data-diva-param-productid	Q7vdOYy4g7y5cL4TVWaIt	The product that is opened in the Configurator. The product must be stored in DIVA and be available in your organization	yes
data-diva-param-onclose-event	onConfiguratorClose	Name of a global function that is called when the visitor closes the Configurator	no
data-diva-param-onsavebasket-event	onSaveBasket	Name of a global function that is called when the visitor adds the product to the basket	no