released

About Default Widgets

 

What is a Default Widget?

A Default widget is a UI component made for one specific purpose (e.g. a Product Sheet). It can be instantiated and used from any application. The objective is to offer common UI views and behaviors accross different applications, as well as allowing a client to use it as a code sample.

Types of widgets

A widget can exist in two different types:

  • Embed: to be integrated with a popin layer.

  • Fullpage: to be integrated as an entire page, like the project page on BryoKitchen website.

Moreover, every widget has a static version and an integrated version.

  • Static version: what front experts will deliver. This uses fake data and is mainly used to demonstrate the layout and what is expected to be seen.

  • Dynamic version: what will be integrated by application developers. This one will display real data and have a real connection with the main application page.

List of existing widgets

Medias

The default widget Medias 🔗 is integrated with Summary step. Application distribution parameter images2DPlans 🔗 Defines if the "Show images" button in the Summary step uses the standard module 'Medias' or not and if the 'Images' or '2D Plans' are downloadable or not.

ProductSheet

The default widget ProductSheet 🔗 is integrated with catalog browser. Application distribution parameter productSheet 🔗 Defines if the product sheet popin in the product card is to use this module or not.

ShareProject

The default widget ShareProject 🔗 is integrated with Summary step. Application distribution parameter shareProject 🔗 Defines if the "Share Project" popin in the Summary step is to use this module or not.

ecoFee

The default widget EcoFee 🔗 is integrated with catalog browser. Application distribution parameter ecoFee 🔗 Defines if the ecoFee popin in the product card is to use this module or not.

myProjects

The default widget MyProjects 🔗 is integrated with catalog browser.

priceInfo

The default widget PriceInfo 🔗 is integrated

  • on the project price info icon (i) in the step 2 - Pick a layout, step 3 - Design your kitchen, and step 4 - Summary. Application distribution parameter projectPriceInfo 🔗 Defines if the price info popin uses this module or not.
  • on the price info icon (i) in the editor, used in worktop editor, wall panel editor, wall edge strip editor, and cabinet editor. . Application distribution parameter editorPriceInfo 🔗 Defines if the price info popin uses this module or not.

NeedMapping

The default widget NeedMapping 🔗 is integrated in the step 2 - Pick a layout. Application distribution parameter needMapping 🔗.

Integration

The widget can be integrated with the application as an iframe (see window.postMessage()). This method safely enables cross-origin communication between window objects, here between a web page and the iframe embedded within it.

  • Iframe Message Format
KeyData typeDescription
eventStringMessage name, which is used as a unique identifier
contentObjectMessage content, which brings arguments to help to handle the event
 
{
    "event": "event name",
    "content": {
        "key1": "value1",
        "key2": "value2"
    }
}

Widget Life Cycle

  • Initialization
  1. Create an iframe dom element
  2. Set the iframe URL with a concatenation of the config WIDGET_URL with the path to your widget version e.g. https://widgets.enterprise.by.me/ProductSheetView/embed.html
  3. Inject the iframe dom element into the document
  • Establish Connection

The main page subscribes to the iframe messages

window.addEventListener('message', callbackFunction)

When the iframe document is fully loaded, the iframe publishes a message to the main page, informing that the widget is ready to use. The iframe also subscribes to messages coming from the main page.

  • Data synchronization

The main page receives a "Listening" message coming from the widget, which indicates that the communication has been established. Thus it is allowed to send the data to render.

When the user makes some actions on a widget, the iframe will send messages to inform the main page to do some more actions in the backend, when these actions are done, the main page sends a message as a feedback to the widget. The widget might need to refresh its view.

  • Destroy

When the user clicks on the button "close", the iframe will destroy the created html elements and remove the related event handlers, sending a "CloseWidget" event to inform the main page.

The main page will destroy the iframe instance and remove the iframe element and event handlers.

Widget integration architecture

The application should have a wrapper, working as a UI module, in order to handle the widget life cycle.

On the widget side, index.js should work as a wrapper handling the widget life cycle. It can also initialize other UI components.

Some Best Practices:

  1. Remember to create helper functions or handlers to mutualize reused code.

  2. Extract common html code between embed.html and fullpage.html. This avoids extra work when changes occur.

Translations

Default widgets have a default set of translations available in English and French. If the application that is using the widget doesn't want to handle the translations, these default values are used.

An application can overload the default translations by passing a "translation" object along with the Iframe message "Open[WidgetName]". This object should contain matching keys with the translation keys currently used by the widget.

It also allows the application to translate other languages than English or French.

← PreviousNext →