Web Components

1. Introduction

In the OMNIA Platform, in addition to being possible to customize how the application works (using the Behaviours), it’s possible to define how it looks like.

Using Web Components, written in Javascript, you can extend the default layout, adding your own elements. Due to the array of supported browsers, the Javascript should be written in ES6 format.

You can add Web Components to a Form, Dashboard, List and Menu. In all scenarios, you can have two different approaches:

• Standalone Web Component: has all the logic to retrieve and process data;
• Mapped Web Component: has the logic to process the data, which is passed as parameters based on the modeled mapping.

A Web Component is defined by:

• its custom element name, the name of the element that will be created to be attached to the page’s DOM;
• its expression, the aforementioned JavaScript code.

Web components are based on existing web standards. You can see the browser compatibility here.

2. Structure of the Web Component

To create a new Web Component it’s necessary to create a Javascript class that extends HTMLElement and adds to the DOM’s custom elements the Web Component.

An excerpt of a Web Component with the minimum configurations would be:

class MyComponent extends HTMLElement {  
  constructor() {
   super();
   
    // Using regular Javascript, create the content of the Web Component
    this.wrapper = document.createElement('div');
    this.wrapper.innerHTML = 'My first Web Component in OMNIA Platform!';
  }

  connectedCallback() {
    // Append the elements to the Web Component
    this.appendChild(this.wrapper);
  }
}

// Add to DOM custom elements you Web Component
// The 1st parameter represents the custom element name (must be the same you write when you add the Web Component to the model)
// The 2nd parameter is the class that will be used to represent your component (the class created in this code block)
customElements.define('omnia-component', MyComponent);

3. Mappings

If it’s necessary to use the data of another element (for example, a textarea to display the value of an attribute or a chart to display the data of a list) you need to model the mappings between the element that owns the data and the Web Component.

To do that, when you are adding the Web Component to the page you need:

• If the page is a Form, set the mapping with the attribute of the entity;
• If the page is a Dashboard, set the mapping with the list that has the required data. When mapping to a list, the page size will also be imposed. Please make sure that you take the page size in consideration designing the feature.

For the remaining scenarios:

• If the webcomponent is in a List, set the mapping with a column list;
• If the webcomponent is in the Menu, mapping is not possible.

After the mapping is configured, the Web Component will receive the data as a parameter. To know how to use it, check the Available parameters section.

4. Available parameters

Each component can receive up to three parameters, depending on the mapping configuration:

• context: the current session information (the structure is represented below);
• elementMetadata: the current element metadata;
• isPreviousValue: boolean value representing if the value corresponds to the previous value (used only when a Form is in the history mode and the mapping is configured; true if the user chooses to see the previous version value of the element);
• isReadOnly: boolean value representing if the WebComponent is in a read-only state (true when a Form is in the history mode, otherwise is false);
• rootMetadata: the metadata of the current root Element;
• state: all the data of the current root Element, in the same structure of the User Interface Behaviours;
• value: if the mapping is configured, has the value of the mapped element;
• valueHasChanged: boolean value representing if the value has changed since the previous version (used only when a Form is in the history mode and the mapping is configured; true if the value has changed since the previous version).

Note: None of these attributes must be used to update the state of the entity. They are only for reading purposes. To interact with the entity data, please see 5. Exchanging data with Web Components

4.1. Using the parameters

To use the parameters, it’s necessary to know when their value has changed.

The approach we recommend is to use the setters of the class to catch the updates.

Check the next code block to see how you can do it.

class MyComponent extends HTMLElement {  
  constructor() {
   super();
   ...
  }
  
  set value(newValue){
    // When the property value changes, update the Web Component content
    this.wrapper.innerHTML = newValue;
  }
}

...

Context structure

Tenant Context

Operation Context

Authentication Context

5. Exchanging data with Web Components

To send data in and out from web components you can use different techniques. To send data in you can use parameters. To send data out and update a given attribute in a form, you need to use a custom event. OMNIA is watching for a ‘value-updated’ event where you can provide a new value to a given attribute.

Example to update the attribute “message” with the value “Hello World”:

this.dispatchEvent(new CustomEvent('value-updated',
      {
        detail: {
          name: 'message',
          value: 'Hello World'
        }
      }));

6. Communicate with OMNIA API

If the Web Component needs data from the OMNIA API, you can use a HTTP Client that is already set.

Check the sample below to know how to do it.

...
// Get the API Client
const apiClient = _Context.createApiHttpClient();
// Execute a Query, using the context data to compose the request address
apiClient
    .doPost(`/api/v1/${_Context.tenant.code}/${_Context.tenant.environmentCode}/application/Queries/MyQuery/Default`, {})
    .then(response => {
        const value = response.data[0].value;
        this.wrapper.innerHTML = value;
    });
...

6.1 Available operations

7. Samples

Click here to access our collection of Web Components and find a set of components ready to use in your applications.