Description: configuratorware designer preview widget - demo

# 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:

Provide one ore more item identifiers for which the preview(s) should be generated. Separate them by commas.
Note that this need to be items that are available for the designer.

Now specify a dimension of your previews. You can use your own. Play around a bit what fits for your use case.

### 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>