Web Components in Oracle APEX

Few years back, I have learned about Web Components. However, I did not get a chance to work on Web Components yet. It's been on my do to list to experiment Web Components, especially with in APEX. My current staycation gave me an opportunity to do this experiment.

Web Components

Web Components is a suite of different technologies allowing you to create reusable custom elements — with their functionality encapsulated away from the rest of your code — and utilize them in your web apps.

In other words, using Web Components, we can create custom elements which are completely self contained with all HTML, CSS and JavaScript (JS) encapsulated in one place. And then we can use these new custom element in our web applications with out the risk of code conflicts. Functionality wise, they are similar to jQuery widgets, however to implement Web Components we don't need any additional libraries, all modern browsers natively support underlying technologies. If you are new to Web Components, then I suggest you to go through Web Components Crash Course video or this article. Above quoted definition is taken from this article. Example we are going to discuss is inspired from the above crash course video.

For the demo purpose, let's consider an example. We want to create a new custom element country-info with an attribute countrycode. When we specify countrycode, then this element should display basic information about the country, by making call to an existing RESTful API.

HTML Source

<country-info countrycode="IN"></country-info>

Target Output

Web Components mainly consists of three main technologies.

HTML Templates
Custom Elements
Shadow DOM

HTML Templates

HTML templates uses new template tag. As the name says, these are just templates and code written inside template tag is not rendered during the page load. We can use templates to hold some HTML/CSS and later, when needed, we can use these templates using JS. You can read further about template element here.

So, let's first create a template for our example.

// JavaScript code
// create template element
const template = document.createElement('template');
// Write HTML and CSS into the template
// with Shadow DOM, CSS defined here will be applicable to custom elements alone
// CSS defined at page level won't be applicable to custom elements
template.innerHTML = `
  <style>
  div.country-data {
    background: #F5F4F2;
    width: 400px;
    margin-bottom: 10px;
    border-bottom: purple 8px solid;
    padding: 4px;
  }
  div.country-data h2{
    color: purple;
  }
  </style>
  <div class="country-data">
    <h2></h2>
    <div class="population">Population: <span></span> Millions</div>
    <div class="area">Area: <span></span> thousand sq.km.</div>
  </div>
`;

Custom Elements + Shadow DOM

Custom Elements are fully valid HTML elements with custom tag names and custom behavior defined using JS. To define a custom element, first we need to create a class that extends HTMLElement and then at the end we need to define custom element tag with the class name using window.customElements.define.

Using shadow DOM, we can isolate the custom element code from the page, so that page CSS, JS won't get conflicted (or used) for custom elements and vice-versa.

JS code for our example

// define class for the custom element
// general convention followed : if the custom element name is custom-element, then CustomElement is used as class name
// our custom element name is country-info, so lets define CountryInfo as class name
class CountryInfo extends HTMLElement {
  constructor() {
    // always call super first in constructor, so that the correct prototype chain is established.
    super();
    // attach Shadow DOM, this isolates the custom element
    this.attachShadow({ mode: 'open' });
    // clone the template content and append to shadowRoot
    this.shadowRoot.appendChild(template.content.cloneNode(true));
    // fetch country data from RESTful API
    // here, we are reading custom attribute countrycode value and using it as input for RESTful API call
    // fill template with data from RESTful API response
    fetch('https://apex.oracle.com/pls/apex/hari/country-data/country/' + this.getAttribute('countrycode')).then(response => response.json()).then(data => {
      this.shadowRoot.querySelector('h2').innerText = data.name;
      this.shadowRoot.querySelector('div.population > span').innerText = data.population;
      this.shadowRoot.querySelector('div.area > span').innerText = data.area;
    });
  }
}
// map country-info tag to use CountryInfo class
window.customElements.define('country-info', CountryInfo);

Using Web Components in APEX

To use this Web Component in APEX, let's save all this JS code to a file. I have copied template code, CountryInfo class code to a JS file. I have used same name for custom element and to the JS file. Having same name for both custom element and corresponding JS file is not a requirement, but it's a good practice. So, it our case, JS file name is country-info.js. Let's upload it in "APEX Application > Shared Components > Static Application Files" section.

Next, create an empty page in APEX and add below code in "Page > HTML Header" section.

<script type="module" src="#APP_IMAGES#country-info.js"></script>

Here, I would like to highlight two points

We are not using standard "Page > JavaScript > File URLs" section to load this JS file, instead we are writing script tag in HTML Header section.
Script tag has type attribute with module as it's value.

When we load JS file using as module, then functions, variables declared in the JS file will not be available in the global scope. For e.g. if you try to run below JS code in browser console, then you will get an error, even though template is declared in the JS file.

console.log(template.innerHTML);

As the aim of using Web Components is to completely make our code re-usable (just plug and play), it's better to use this approach to load Web Component JS files as modules. You can read more about JS Modules here.

Next, create a "Static Content" region with below source in the APEX page.

<country-info countrycode="IN"></country-info>

That's it and here is the demo. When we inspect country-info element using browser developer tools, we can see shadow-root and the template we have defined with country data.

Now, whereever we want to use our custom element, then we can simply include the country-info.js file in page and we can write country-info HTML tag. Everything will magically works.

Adding User Interaction

Let's make this more interesting by adding some flexibility for users to choose which countries data they would like to see. For this, let's create a checkbox group item for countries, with Country Name as display value and Country Code as return value. Page item name in this demo is P35_COUNTRIES.

Now, modify the "Static Content" region source as below

<div id="country_data_container"></div>

Next, Create a Dynamic Action as below

Name: Display Country Data (or any proper name)
When:

Event: Change
Selection Type: jQuery Selector
jQuery Selector: input[name=P35_COUNTRIES]

True Action:

Action: Execute JavaScript Code
Settings:

Code: As shown below

JS Code:

// get country code from the checkbox item
let countryCode = $(this.triggeringElement).val();
// get country-info tag for the countryCode, if it's previously added to the DOM
let countryNode = $("country-info[countrycode=" + countryCode + "]");
if ($(this.triggeringElement).is(':checked')) {
    // check if element already exists, then just show it
    if (countryNode.length == 1)
        countryNode.show();
    else
        // otherwise add it to DOM
        $('#country_data_container').append('<country-info countrycode="' + countryCode + '"></country-info>');
}
else {
    // unchecked, hide it
    countryNode.hide();
}

That's it and here is the demo.

As I said above, this is a little experiment I did with the Web Components. This is a simple Web Component and we are not using template slots, custom element lifecycle callbacks etc. You can refer webcomponents.org to find out some useful and advanced Web Components published by others.

Conclusion

Web Components are clean and elegant. Once we build a web component, we can re-use it any web application without any fear of conflicts. As we have seen above, we can use Web Components in APEX in relatively simple way. However, to make use of APEX framework features like server-side conditions, authorization schemes etc. it is better to wrap Web Components as APEX plug-ins. Then we can get best of the both the worlds.

Have you used any Web Components in your APEX applications? What did you like most about using Web Components and what challenges have you faced while using them in APEX? Post your comments below.

Thank you.

Few tips on Gantt Charts

Oracle APEX offers several beautiful chart types which are based on Oracle JET Data Visualizations. Gantt Chart is one such beautiful and useful chart. However, when I have searched in Google for some help on Gantt Charts, there are not many blogs posts talking about it. So, I thought, I could write one with few basic tips which I have learned this year. I have used Gantt Chart to display employees calendar data and my targeted output was something like below. Pic-1 Looks simple, correct? However, it's little tricky to get there. Multiple Tasks Per Row: When I look at the output, first I thought, I will have to write a query which gives tasks data and employee data with 1 row per task. That is, if there are 10 tasks to be displayed, then there should be 10 rows in SQL query output. But, it's not correct. Instead, I should have 1 row for each task + 1 row for each employee (parent). So I need to write a query which will output data in below format. Pic-2 A

Oracle APEX Tips & Techniques

Search This Blog