Microfrontends

What is a microfrontend?

What we call "microfrontends" are the simplest way to bring you our modules to your application. Sometimes will also refer to them as "modules" since microfrontends is just a technical term for how to implement them. At the end, you will get the module in your application by inserting the microfrontend which implements it.

Technologies: Our microfrontends are builtin using web technologies (HTML, CSS, JavaScript) so they can be used in any website or any application (mobile, desktop, etc.) that can embed webviews. The base of all of them is a webcomponent container, but inside this container it will render a React tree of components that implements the module.
Data and Authentication: All the data is fetched directly from our API so you don't need to provide any data to the microfrontend aside from the input parameters. In those cases where the module needs to fetch API data owned by an user, you will need to provide a JWT token previously obtained from the Connect API using your API key (server to server authentication).
Styling: The CSS applied to the page where the microfrontend is inserted doesn't affect to the microfrontend itself and vice versa. There are some CSS variables available to customize the microfrontend to your needs.
Events: The microfrontend could emit events to notify the parent application about something that happened inside it in some cases. We provide a way to listen to those events from the parent application.

Getting started with microfrontends

Add the script to your application

In order to be able to use any of our microfrontends, you just need to add the following script to your web page or the webview where the microfrontend will be inserted. Inside the <head> tag is the best place for it.

Add the script to your application
<head>
  <script
    type="module"
    src="https://assets.clever.gy/clevergy-modules.js"
  ></script>
</head>

The inserted script will define all the microfrontends so you can use them anywhere in your web page or the webview.

Insert the microfrontend in your application

All our microfrontends are based in a webcomponent that you can insert by using a simple tag and some parameters such as this:

Microfrontend example
<clevergy-module-name 
  data-parameter-name="parameter-value"
  data-another-parameter="another-parameter-value"
/>

That one is just an example. Each module has its own name and parameters. Check the modules catalog for more information about each microfrontend, its parameters, CSS variables and events.

Customizing the style

In order to customize the style of the modules, you can use the following CSS variables. Clevergy variables are typed with the --clevergy prefix to avoid colisions with your local CSS styles.

Common CSS variables

This common CSS variables are used along our design system.

Common CSS variables
<head>
  <style>
    :root {
      /* 
       * Font family: 
       * The font must exist in the web page. For custom fonts you have
       * to load the font face in the web page by yourself by using CSS 
       * or some third party service for fonts hosting such as Google Fonts.
       */
      --clevergy-font-family: Verdana, Roboto, Georgia, Courier; 

      /* 
       * Common colors:
       * The colors are used by the design system to provide a consistent look and feel.
       */
      --clevergy-color-primary: #e57200;
      --clevergy-color-secondary: #004571;
      --clevergy-color-text: #004571;
      --clevergy-color-subtext: #737373;    
      --clevergy-color-unselected: #a2bdcb;
      --clevergy-color-border: #d9d9d9;

      /* 
       * Module header variables:
       * These variables are used to customize the module header.
       */
      --clevergy-module-header-title-color: #004571;
      --clevergy-module-header-action-color: #004571;

      /* 
       * Module container variables:
       * These variables are used to customize the module container.
       */
      --clevergy-module-container-background: none;
      --clevergy-module-container-border: none;
      --clevergy-module-container-border-radius: none;
      --clevergy-module-container-box-shadow: none;
      --clevergy-module-container-padding: none;
      --clevergy-module-container-margin: none;

      /* 
       * Specific component variables:
       * These variables are used to customize the specific components.
       */
      --clevergy-button-color: #e57200; /* Color of the button. Usually the background (or text when is inverted) */
      --clevergy-button-contrast-color: white; /* Contrast color. Usually the button text (or background when is inverted) */
      --clevergy-button-border-radius: "8px"; /* Border radius of the button */
    }
  </style>
</head>

info

If you don't define any CSS variables, the module will use our default values.

Customizing the style of a specific module

As :root variables are global, they will affect to all the modules. If you need to customize the style of a specific module, you can use the tag name to scope the CSS variables to the module.

Customize the style of a specific module
<style>
  clevergy-module-name {
    --clevergy-button-color: #e57200;
    /* any other variable */
  }
</style>

Specific module CSS variables

There are some modules that have specific CSS variables, so check the modules catalog to see if the module you are interested in has specific CSS variables.

info

If there are specific variables that you wish to control, reach out to your CSM so that we can offer a solution.

Listening to events

When a module needs to notify the parent application about something that happened inside it, it will emit an event. You can listen to those events by using the clevergy_subscribeToEvent function.

Because the function clevergy_subscribeToEvent is only available after our JS script is fully loaded, it's recommended to call it on the window.load event:

Listening to events
<script>
  window.addEventListener('load', function () {
    // Subscribe to the event
    clevergy_subscribeToEvent('INTEGRATION_SMARTMETER_FAILED', function (data) {
      console.log('INTEGRATION_SMARTMETER_FAILED', data);
      // do stuff...
    });

    // Subscribe to another event
    clevergy_subscribeToEvent('WHATEVER_EVENT', function (data) {
      console.log('WHATEVER_EVENT', data);
      // do stuff...
    });
  });
</script>

Not all modules emit events, so check the modules catalog to see if the module you are interested in emits events.

Language

All modules are shown in Spanish by default. To specify the language there is an optional parameter for it named data-language which allows these values:

es-ES Spanish (by default)
ca-ES Catalán
gl-ES Gallego

Language example
<clevergy-energy-prices
  data-language="ca-ES"
/>

Authentication

For those microfrontends that need to fetch data from our API, you have to provide a JTW token. To pass the JWT Token to the microfrontend, you have to set a data-token parameter with the JWT token value.

Go to Authentication section to see how to get a JWT token.

Authentication example
<clevergy-module-name data-token="your-jwt-token" />

Token expiration

After 1 hour, the token expires, so you do need to create another new one.

Not all modules need authentication, so check the modules catalog to see if the module you are interested in needs authentication.

What is a microfrontend?​

Getting started with microfrontends​

Add the script to your application​

Insert the microfrontend in your application​

Customizing the style​

Common CSS variables​

Customizing the style of a specific module​

Specific module CSS variables​

Listening to events​

Language​

Authentication​