LOOK4 Optics Configurator Widget (Beta)

The SPECTARIS catalog format defines data structures that can represent the specifications of all kind of products, including e.g. contact lenses with complex dependencies between article features and ranges. It is a non-trivial task to create an order entry UI based on that data that is easy, fast, consistent, and reliable.

Therefore, LOOK4 offers a pluggable HTML-/JavaScript based widget that can be easily integrated into web sites and native applications (desktop and mobile) alike.

The widget consists of a very small JavaScript component (without any dependencies on third-party libraries and frameworks like e.g. jQuery), and an API endpoint in LOOK4 Optics Webservices, providing all required product data.

Basic Integration

To embed the configurator widget in an HTML page, insert the following snippet:

<div class="l4oconf-container" data-supplierid="DE12345" data-catalogid="catalog.xml" data-articleid="ABC"></div>
<script src="<SCRIPTURL>"; type="text/javascript" async="async"></script>

Replace <SCRIPTURL> depending on the LOOK4 Optics environment that you want to work with:

Test/Stating environment:
https://configwidget-test.look4optics.com/v1/script.js
Production environment:
https://configwidget.look4optics.com/v1/script.js

Available data attributes for configuration and data exchange

data-supplierid, data-catalogid, data-articleid:
Required. IDs to identify an article in LOOK4 Optics, as provided in the catalog infos web service or catalog header data.
data-culture:
Optional language tag used for number formatting, e.g. en-US or de-CH. If undefined, the first entry of the user agent’s Accept-Language header will be used.
data-orderparams:

Optional. This string is formatted as a URL query string so that it can be easily appended to URLs and e.g. passed to or from the hosting application’s backend server.

Each article feature is represented by an URL argument key feature_FeatureTemplateIDInCatalog, and the assigned value is the feature value from the catalog, as expected in SPECTARIS orders. In addition, quantity parameters contain the selected quantity.

If the article allows for configuration of two items in one step (e.g. for contact lenses: right and left side), the first occurrence of each URL parameter refers to the first item, the second occurrence to the second item.

  • When written by the application: Allows to prepopulate feature values. Single values (e.g. based on data already captured in other parts of the application) or an entire configuration (e.g. based on an earlier order) can be provided. If the configuration is invalid, the widget will try to populate at least as many values as provided.
  • When read by the application: Allows to retrieve the current configuration as represented by the order form.
data-na-label:
Optional. Allows to overwrite the default “n/a” string for dropdowns.
data-labelshortenerthreshold:
Optional. When set to values > 3, text labels will be “ellipsified” to the maximum length defined by this attribute.
data-access-token:
Optional. Provides the LOOK4 ID OAuth access token used for authenticating requests to the configurator’s backend service. Only authenticated requests will get access to non-public articles (private labels) as well as prices. See the LOOK4 ID (v2) documentation for details on how to register your client application and how to get an access token.

Custom Events

orderStatusChanged:

Required. This event is raised whenever the status of the current configurations changes from incomplete/invalid to complete/valid or vice-versa.

The provided event object has a boolean flag detail.ready, indicating whether the current configuration (available from data-orderparams) is valid/complete and could be used to create a valid order.

Your web site could use this value to enable or disable a Submit button, and whenever the Submit button is clicked, you can simply read the data-orderparams value and know that represents a valid configuration.

errorOccured:

Optional. This event is raised whenever an unexpected error occured.

The provided event object has an object detail.status_code. This will be an HTTP status code, whenever an HTTP error has occured, and will be set to "internal", whenever a JavaScript error has occured.

accessTokenExpired:
Optional. This event is raised when the provided access token (see the data-access-token attributed) is rejected by the configurator backend service. The default expiration time of a LOOK4 ID access token is 1 hour. To make sure that the embedded configurator continues to work after the initial data access token expired, please subscribe to this event. In the event handler you are required to set the data-access-token to a new, unexpired token. Otherwise, all calls will result in an 401 error.

Initializing the widget

l4oconf.init()
This method is called automatically once after loading the widget script. It might be called later to reset the widget (e.g. the articleID has changed). This method will not initialize the widget if any of the l4oconf-container attributes data-supplierid, data-catalogid or data-articleid is not set. In this circumstances, one should call l4oconf.init() immediately after setting those attributes.

CSS Customization: Design, Layout, Labels

The widget appends simple DOM elements as children to the #l4oconf-container div container. All classes or IDs of child elements have a l4oconf- prefix so that you can easily target all elements.

This is the basic strucuture inside the parent div container:

  • article image
  • div elements for ID, name, description
  • definition lists for describing article features
  • a table for the actual configuration form

Simplified example of the dynamically generated markup:

<img class="l4oconf-img-large" src="https://mediathek.look4optics.com/xmwxcnnc.view">
<div class="l4oconf-id">1D4-30P-REV</div>
<div class="l4oconf-name">1 DAY ACUVUE TruEye (30er PACK)</div>
<div class="l4oconf-description"></div>
<dl data-feature="Material">
    <dt>Material</dt>
    <dd>Narafilcon A (Silikon-Hydrogel)</dd>
</dl>
<dl data-feature="Characteristics">
    <dt>Eigenschaften</dt>
    <dd>"123"-Handhabungsmarkierung und Visibility-Tint</dd>
    <dd>Hydraclear 1 Technologie</dd>
    <dd>Integrierter Benetzungswirkstoff durch Hydraclear-Technologie</dd>
    <dd>UVA-und UVB-Schutz</dd>
</dl>
<dl data-feature="Brand">
    <dt>Marke</dt>
    <dd>Johnson &amp; Johnson</dd>
</dl>
<dl data-feature="WaterContent">
    <dt>Wassergehalt</dt>
    <dd>46,00 %</dd>
</dl>
<table class="l4oconf-content-table">
    <thead>
        <tr>
            <th></th>
            <th>
                <input value="🗑" type="button">
            </th>
            <th>
                <input value="🗑" type="button">
            </th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td>Sphäre</td>
            <td>
                <select data-feature="Sphere" class="l4oconf-valid" name="Sphere">
                </select>
            </td>
            <td>
                <select data-feature="Sphere" class="l4oconf-unused" name="Sphere">
                </select>
            </td>
        </tr>
        <tr>
            <td>Radius</td>
            <td>
                <select data-feature="RadiusBasecurve" class="l4oconf-valid" name="RadiusBasecurve">
                </select>
            </td>
            <td>
                <select data-feature="RadiusBasecurve" class="l4oconf-unused" name="RadiusBasecurve">
                </select>
            </td>
        </tr>
        <tr class="l4oconf-quantity-table-row">
            <td></td>
            <td>
                <input min="1" max="1000000" step="1" value="1" type="number">
            </td>
            <td>
                <input onfocusout="l4oconf.repaint()" min="1" max="1000000" step="1" value="1" disabled="disabled" type="number">
            </td>
        </tr>
        <tr class="l4oconf-price-table-row">
            <td></td>
            <td>n/a</td>
            <td>n/a</td>
        </tr>
    </tbody>
</table>

Examples of how to style these elements can be found in our Static website demo.

Please note that you have to use CSS content properties to define text labels for general elements like “quantity”, “price” etc., and even error messages. This way you have full control over the wording and can also handle localization/globalization of label texts.

Requirements

Supported browsers:

  • Google Chrome
  • Mozilla Firefox
  • Microsoft Edge
  • Microsoft Internet Explorer 11

Demos

Static website demo:
https://configwidget-test.look4optics.com/v1/demohost/index.html
Windows Desktop application using .NET WinForms and Internet Explorer:

Not publicly available yet. Please let us know if you are interested.

Basically, you create a local, embedded HTML page hosting the L4O config widget. Everything you need to know to integrate this HTML page with your application is described in this Microsoft How-To: Implement Two-Way Communication Between DHTML Code and Client Application Code

FAQ

Q: The widget does not show any content

A: Check if you fulfill the browser Requirements. Have you initialized the widget correctly? (See Initializing the widget)
The widget will show an error if the requested article is no longer in the catalog. (See Custom Events for more information about catching errors)
Contact / Legal