Web Components Tutorial - OMNIALowCode/omnia2 GitHub Wiki

Introduction

This tutorial is designed to add an IBAN (International Bank Account Number) field to an Agent entity on the platform, and provide a different way for the input of that number than what the platform natively supports, as well as performing validation on that IBAN, all using a HTML/JavaScript Web Component.

Furthermore, we will add a map to the platform, to explore a common extensibility scenario.

This tutorial will drive you to explore the possibilities in the OMNIA platform to extend the default behavior of the user interface.

Prerequisites

This tutorial assumes that you have created a tenant based on the OMNIA Modeling Template, and are using a user with modeling privileges (preferably not the subscription's master account) to access this tenant. See this page to assist in tenant creation.

This tutorial also requires an understanding of the concepts driving the platform, which are described in this page.

If you are performing this tutorial on top of a tenant that was already used to execute a previous tutorial, when there is an instruction to create an Entity and then perform further operations on that entity, if you already created one with the given name, you can reuse the one that already exists.

Download the JavaScript files that can be found in this tutorial's folder:

  1. Validate IBAN that will be used to validate the input data provided by the user, and compose a differently-styled form.

  2. Map to embed a map from Google Maps.

Obtain a Google API Key and replace it in the Map.js file. Follow the guide Google provides.

Adding an IBAN

  1. Start by accessing the Modeler.

    1.1. Open the left-side context menu (click in arrow next to the name of the tenant you are currently on).

    1.2. Choose the option Modeler.

  2. Through the top navigation menu, access Entities > Agents. Create an Agent Type (Add new button in the context options in the bottom of the screen), and set its Code and Name to "Customer".

  1. Add an Attribute to Customer, under General, with the Code and Name of IBAN, of type Text.

    3.1. In the Behavior tab, remove the Required checkbox.

    3.2. In the Interface tab, remove the Visible checkbox.

  1. Save the Customer Agent, via the context option in the bottom of the screen.

  2. Access Other > Web Components in the menu. Create a Web Component (Add new button in the context options in the bottom of the screen) with the name IBANValidator, and upload IBANValidator.js that you downloaded at the start of this tutorial.

  1. Access Entities > Agents again, and edit the Customer agent.

    6.1. In the General tab, add a UIElement with the Code and Name PaymentType, of type WebComponent. Identify IBANValidator when selecting the Component.

    6.2. Make sure that the PaymentType element, in Interface, is set to a Size of 10, so that it has its own row.

  1. Save the Customer Agent.

  2. Access the application. Go to Configurations > Customer > Create and access the customer creation form.

  3. Set the Payment Type to Bank Transfer. Input an invalid IBAN. Verify the form displays an error.

  4. Input a valid IBAN (for example, you can try one of the following: PT50 1234 4321 1234 5678 9017 2, GB29 NWBK 6016 1331 9268 19, ES91 2100 0418 4502 0005 1332). The platform lets you save as normal.

Adding a Map

  1. Access Entities > Agents again, and edit the Customer agent.

    1.1. In the General tab, add an Attribute with the Code and Name ShippingAddress, of type Text area.

  2. Save the Customer Agent.

  3. Access Other > Web Components in the menu. Create a Web Component (Add new button in the context options in the bottom of the screen) with the Code Map, and upload Map.js that you downloaded at the start of this tutorial. (if you want to use another code, you have to rename the WebComponents.Map object in the script to the code of your Web Component in the platform)

Do not forget to include your API key in the file before uploading!

  1. Access Entities > Agents again, and edit the Customer agent.

    4.1. In the General tab, add a UIElement with the Code and Name ShippingMap, of type WebComponent. Identify Map when selecting the Component.

    4.2. Make sure that the Map element, in Interface, is set to a Size of 10, so that it has its own row.

  2. Access the application. Go to Configurations > Customer > Create and access the customer creation form.

  3. Verify that the map is shown, and that it is responsive to the values in ShippingAddress.

Next Steps

This is the last tutorial in our current proposed order. If you skipped any of the others, now is a good time to go back and check them out! Otherwise, just start developing in the platform - there is no better way to learn than to start working on that project you've just gotten proposed.

If you haven't done the Cloud Extensibility Tutorial, you should take the opportunity to do so, as its example case is similar to the one shown in this tutorial, but the validation is performed in a C# script instead of in a JS web component.