configuratorware designer preview widget - demo & documentation

What it is and how it works

The designer preview widget allows the creation of preview image data for a provided logo for the default printing area and method for a number of items.
Normally this is used to display quick previews of items in online shops: "How does my logo look on this item?"

It works like this:

1. There is a widget in which the user can upload their image - and if wanted - remove the background.
2. The widget is simply included as an Iframe. You can put it wherever you want as long as it is available within the page (above product lists, in overlays...).
3. The widget also creates the image previews basically by "screenshotting" (it does a little more than that obviously ;)) the combination of item and uploaded image (it does it client side).
4. The uploaded image is put into local storage, to be able to change the page without having to uplad the image again.
5. After the widget is loaded you can provide it with a list of item identifiers you want to get preview image data for. You do this by sending a postMessage to it.
6. As soon as the widget has both infos: an uploaded image in local storage and a list of item identifiers it starts returnin postMessages that contain the preview images one by one.
7. You can now use this image data to display the preview images.

A working demo

The widget is integrated as an IFrame, upload the image that is to be previewed on the items here:

After adding an image in the widget and sending item identifiers to it the preview images appear here:

Technical Integration Documentation

Hint: check out the example's code by looking at this page's source code

Integrate the widget into your site

The widget is simply integrated in an IFrame:

<iframe name="configurator" src="/designer-preview-widget" frameborder="0" style="width: 400px; height: 530px;"></iframe>

You can use the ?_language GET Parameter to set a language:

<iframe name="configurator" src="/designer-preview-widget?_language=de_DE" frameborder="0" style="width: 400px; height: 530px;"></iframe>

A good size is 400px x 530px, maximum good looking width is 600px

Know when the widget is loaded

As soon as the widget is fully loaded it sends a postMessage of the type "configuratorware_designer_preview_widget_loaded". Listen to the widget like this:

<script type="text/javascript">

        // register a post message listener to listen to the widget
        window.addEventListener('message', receiveMessage, false);

        // there are two message types which are sent by the widget:
        // "configuratorware_designer_preview_widget_loaded": the widget is fully loaded. You can then send item identifiers via setItemIdentifiers
        // "configuratorware_designer_preview_widget_dataready": a preview for an item is ready. The src data comes as a payload
        function receiveMessage(message) {
            switch (message.data.type) {
                case 'configuratorware_designer_preview_widget_loaded':
                    console.log('MESSAGE: Widget loaded');

                    // item list can be set directly after the widget is loaded, e.g. like this:                         
                    /*
                    message.source.postMessage({ type: 'setItemIdentifiers', identifiers: [
                        'identifier_1',
                        'identifier_2',
                    ]});
                    */
                    // this is commented out because in our demo we use the identifiers from the input 

                    break;               
            }
        }
    </script>

Send item identifiers to the widget

As soon as the widget is loaded you can send it item identifiers to get preview images for them. Also you can set or swith teh size of the preview images:

<script type="text/javascript">

        // request previews for the items from the input
        document.getElementById('addItems').addEventListener('click', function addItems() {
            var identifiers = ['identifier_1', 'identifier_2'];                  
            frames.configurator.postMessage({
                type: 'setItemIdentifiers',
                identifiers: identifiers,
            });
        });

        // switch size of preview images - normally you do this only once at the beginning
        document.getElementById('size').addEventListener('change', function setSize(evt) {
            const [width, height] = evt.target.value.split('x');
            frames.configurator.postMessage({
                type: 'setSize',
                size: { width, height }
            });
        });
    </script>

Finally receive the preview image data per item

Receive data per item and set it to your html img:

<script type="text/javascript">

        function receiveMessage(message) {
            switch (message.data.type) {
                case 'configuratorware_designer_preview_widget_dataready':
                    console.log('MESSAGE: preview ready for item ' + message.data.identifier);

                    // the job of the calling site is to wait for the preview image data and put it at the right spot when it is returned, like this:
                    const elementId = 'img-' + message.data.identifier;

                    // create a new image element for the preview (of course you can also just change the src of an existing one)
                    const img = document.getElementById(elementId) || (() => {
                        const element = document.createElement('img');
                        element.id = elementId;
                        document.getElementById('images').appendChild(element);
                        return element;
                    })();

                    // set the data. that's it ☺
                    img.src = message.data.image;
                    break;
            }
        }
    </script>