Integrating 6M Components
This page explains how you, as a website owner or CMS editor, can use 6M components on your own site. For a simple integration, you only need basic HTML skills.
The Components Catalog
First, you should have a look at the components catalog, the overview of the currently existing 6M components. Select one or more components you wish to use, then read the rest of this page to learn about their integration into your site.
Simple Integration
Integrating a 6M component into your website is simple. You need to add some scripts and stylesheets, then create an instance of the component.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>6M Example</title>
<!-- polyfill.io is a service that loads the right polyfills, customized for the current browser.
Rather than having each 6M component ship polyfills, this will ensure consistency and performance. -->
<script type="text/javascript" src="https://polyfill.io/v3/polyfill.min.js"></script>
<!-- Cotton Ball is the 6M event handler -->
<script type="text/javascript" src="https://api.tui.com/ml/cotton-ball/" async defer></script>
<!-- The UI Elements library provides styled user interface elements such as buttons and form fields -->
<script type="module" src="https://cloud.tui.com/common/ui-elements/master/ui-elements/ui-elements.esm.js" async="async" defer="defer"></script>
<script nomodule src="https://cloud.tui.com/common/ui-elements/master/ui-elements/ui-elements.js"></script>
<link rel="stylesheet" href="https://cloud.tui.com/common/ui-elements/master/ui-elements/ui-elements.css">
<!-- Each component has a script link -->
<script src="https://cloud.tui.com/6m/beone-content/hotel-gallery-6m/master/main.js" async defer></script>
</head>
<body>
<!-- This is an instance of the component.
You can create multiple instances of the same component on one page, if necessary. -->
<tui-hotel-gallery product-code="GPA10011"></tui-hotel-gallery>
</body>
</html>The overhead of loading several scripts and stylesheets for just one component may seem over-complicated, but keep in mind that a microfrontend website usually contains multiple components, and then it’s a good thing that basic stuff is loaded only once.
Skeleton Placeholders
Components are loaded with some delay, especially with the defer async properties on the Cotton Ball’s script tag (which is recommended). This is intentional, but there’s a little downside: The element is empty and takes up no space until it is initialized and takes up its real width and height. The initialisation will lead to an annoying flickering effect.
To avoid this, you can fill the component with a placeholder called skeleton. This placeholder has the final dimensions of the actual component, and it shows the structures of the main contents, usually in grey. Skeletons are rendered with inline CSS. For example, a skeleton might look like this:
The source code for this skeleton looks like this:
<div style="background: #f4f4f4; margin: 30px 0; padding: 30px; display: flex; flex-direction: row; flex-wrap: no-wrap; justify-content: space-between; align-items: center">
<div style="margin-right: 30px; width: 80px; height: 80px; background: #ddd; border-radius: 50%"></div>
<div style="flex: 1 0;">
<div style="background: #ddd; height: 20px; margin-bottom: 10px"></div>
<div style="background: #ddd; height: 20px; margin-bottom: 10px"></div>
<div style="background: #ddd; height: 20px;"></div>
</div>
</div>You will most likely have seen something like this on the web. All the cool kids are using it!
Each 6M component comes with one or more skeletons as HTML snippets. You can insert these snippets into the component tag, and they will show a preview of the component until the real component is loaded.
NOTE: Some 6M components have different variants. Be sure to pick the correct skeleton in order to have a skeleton with the correct dimensions.
Interacting with components
NOTE: You need at least some basic knowledge of JavaScript to use this feature.
6M components communicate with their environment through events, i.e. they send (“publish”) and receive (“subscribe to”) small message objects.
You as the owner of the host page in which the component is embedded, can use this to interact with the component: You can either subscribe to an event and act on it when you receive it. Or you can send an event to a component and influence its behaviour.
Sending an receiving events happens through the Cotton Ball Event Handler. It has the publish method which allows you to send out an event, and the subscribe method to receive events.
Receiving events from a component
Many components emit events to which you can “subscribe” in order to act on them, e.g. for tracking, changing the view or connecting it with another component.
Consider the following example, where you would subscribe to an event of an imaginary image gallery component. The event would be triggered when a user clicks a button to show the next image:
tuiCottonBall.subscribe("image-gallery", "*", "image.next_selected", function(componentName, scope, eventName, data){
// do something, e.g. tracking
})The first three parameters are: the tag name of the component, the scope (see below), and the event name. The fourth parameter is a callback function which receives the event parameters: The component’s tag name, scope, and the event name again, then finally the event data.
Sending events to a component
Let’s assume our image gallery whould allow setting the current image from the outside, through an event. In this case, you would publish the appropriate event, which could look something like this:
tuiCottonBall.publish("image-gallery", "*", "image.show_next", {})The parameters here are: tag name, scope, event name and payload. In our example, the payload is an empty object, but depending on what the component expects, the object could contain one or more values.
To learn about the events of a given component and the data it publishes or expects, consult the component’s documentation in the catalog.
Event scoping
Each event is sent in a certain scope. Scopes allow grouping components with others, or restricing events to the host context. The reason for this is that sometimes you may have multiple instances of a component within one context (for example a single-page application). In such a case, you may want to send a given event to only one instance of the component, but not to another one.
In both the publish and the subscribe functions above, the second parameter is the scope. All events published within a certain scope are broadcasted only to components within the same scope. The scope may contain an arbitrary string which is assigned through the scope attribute on the component’s HTML element, e.g.
<tui-image-gallery class="tui-component" scope="first-page"></tui-image-gallery>If there’s no scope attribute on the component, the wildcard scope * is applied internally. When an event is published with the * scope, it is broadcasted to all components listening on the same component/event name combination. When a component subscribes to an event using the * scope, it will receive all events with the same component/event name combination.
When more than one 6M Component is embedded on a web page, they can communicate with each other. In fact, some components even just make sense paired with at least another one.