Skip to main content

Microfrontends

What is a microfrontend?​

A "microfrontend" is the simplest way to bring you our functionalities to your application.

  • Technologies: Our microfrontends are built 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. Inside this container it will render a React tree of components.

  • 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 microfrontend needs to fetch API data owned by a 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 does not affect 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-microfrontend-name 
  data-parameter-name="parameter-value"
  data-another-parameter="another-parameter-value"
/>

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

Customizing the style​

In order to customize the style of the microfrontends, you can use the following CSS variables. Clevergy variables are typed with the --clevergy prefix to avoid collisions 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;

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

      /* 
       * Microfrontend container variables:
       * These variables are used to customize the microfrontend 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, it will use our default values.

Customizing the style of a specific microfrontend​

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

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

Specific microfrontend CSS variables​

There are some microfrontends that have specific CSS variables, so check the microfrontends catalog to see if the microfrontend 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 microfrontend 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 microfrontends emit events, so check the microfrontends catalog to see if the microfrontend you are interested in emits events.

Language​

All microfrontends 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
  • eu-ES Basque
  • en-US American English
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 JWT 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-microfrontend-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 microfrontends need authentication, so check the microfrontends catalog to see if the microfrontend you are interested in needs authentication.