Oracle APEX - Customising Oracle JET charts

In this blog post, we will explore the process of customising Oracle JET components within an Oracle Application Express (APEX) environment and show how doing this enables us to unlock many more display options that are not presently available natively through standard APEX chart configuration screens.

Whether you're an experienced APEX developer, or simply interested in data visualisation, this guide aims to provide you with the knowledge and techniques necessary to fully utilise Oracle JET's capabilities.

Throughout this post, we will examine two essential resources

• the Oracle JET Cookbook Styles to explore colours, borders, legend settings, and more
• the Oracle JET documentation as our guide, offering detailed options to fine-tune and enhance your charts

These documents will be helpful guides as we explore how to change charts the way we want.

We will focus primarily on popular chart types such as Bar and Pie charts, discovering a wide range of options to modify and tailor them to meet your specific requirements. The principles that we apply to these two types of charts can, however, be extended to all the other JET types of charts.

About Oracle JET

Oracle JET (JavaScript Extension Toolkit) is a collection of open-source JavaScript libraries for developing modern web applications.

The integration of Oracle JET with APEX (Application Express) offers developers a wide range of possibilities for creating dynamic and visually appealing applications. Components such as charts and form items are already part of the APEX framework, providing developers with a solid foundation to work with.

While the initial integration of JET components into APEX may appear straightforward, unlocking the full potential and customising them further requires a deeper understanding. APEX allows for declarative configuration of a limited set of JET component attributes, offering some level of customisation out of the box.

If you're interested in exploring the extensive range of capabilities offered by Oracle JET, this blog post will introduce you to the ins and outs of digging into JavaScript code to discover all the possibilities that can be unlocked.

Official documentation about Oracle JET and its integration with Oracle APEX can be found here.

About Oracle JET components in Oracle APEX

As stated earlier, certain JET components are already integrated into APEX. Charts, for instance, made their debut in version 5.1, which was released in December 2016 and brought significant added value to the product.

In addition to the continuous introduction of numerous enhancements, it is worth noting that the range of declarative (configuration) options available for charts remains somewhat limited. This limitation could stem from either the maximum number of parameters a plugin can handle (capped at 25) or a deliberate business decision to focus on supporting the most commonly used attributes.

Let's take the Pie chart as an example. Personally, I find it visually appealing. Nonetheless, there might be instances where you wish to customise it to align with the overall aesthetic of your application. Perhaps your client requires a specific colour scheme that maintains consistency across the application, or you may want to indulge in your own creativity, exploring different colours and styles, as I often enjoy doing myself. :)

For example, if you desire a chart resembling the one below, you will have to employ JavaScript code to modify additional attributes that are not accessible through the declarative options in the APEX application builder itself.

The modified example has undergone significant changes to achieve a more modern appearance compared to the default one. It includes custom colours, a background and border for the legend, feeler colour, label in the centre of the chart, and other enhancements. These alterations combine to create a visually appealing and contemporary look.

How to customise Oracle JET Components

Determining the connection between attributes and their respective outcomes solely by reading the documentation can be a challenging task. To help us with that Oracle provides a style editor in the Oracle JET Cookbook, which offers an interactive method for exploring a wider range of attributes for each component.

You can find the specific cookbook page we are referring to for the pie chart example here.

While this tool is helpful for understanding the level of customisation offered by Oracle JET, it doesn't provide an easy way to implement these changes into our Oracle APEX application. As a result, you'll have to dig into the API documentation which, I find, isn't as clear as it could be.

Apart from playing with styles, you can find a direct link to the relevant documentation section on the tool. Specifically, in our example case above, the essential class to work with is the ojChart class.

Type Definitions

Our example will focus only on the Object types that are documented within the Type Definition section.

The crucial aspect here is to generate an object that will be passed to the Initialisation script in Oracle APEX. Within this object, we will override the default parameter values for the particular chart type. This is similar to how the Application Builder translates your chart parameter settings into an object.

This bit of code is then set in the Application builder, under Chart region > attributes > Advanced >  Initialisation JavaScript Function

Here is a simple example code structure of the initialisation function:

function( options ){
	options.<type Definition> = {
    	<property 1>: "<value>",
        <property 2>: "<value>",
        <property 3>: "<value>"
    };
    return options;
 }

It is crucial to note that the camelCase convention is obligatory when defining objects. For example, the PieCenter definition type should be expressed as "pieCenter" in the initialisation code.

Here is a functional example that demonstrates how to position some text in the centre of a pie chart, similar to the example mentioned earlier.

function( options ){

    options.pieCenter =  {
        label: 'Project Cost',
        labelStyle: 'font-size:30px; color:black;',
    };
    
    return options;
}	

Common type definitions

Let's explore some of the possibilities that Oracle JET offers that apply to the majority of JET charts.

StyleDefaults

This object type contains properties that affect the look and feel of the chart itself, for example, series colours, marker shapes, and other style attributes.

Please note that not all the properties apply to every chart type.

Legend

The Object type that specifies the style, positioning, and behaviour of the legend. These are common to any legend regardless of the chart type.

Chart-specific type definitions

In this section, we will explore a specific type definition for the pie chart.

PieCenter

The Object type defines the centre content of a pie chart. Either a label can be displayed at the centre of the pie chart or custom HTML content.

You might want to explore the documentation for more specific type definitions.

Pie Chart Example

Let's take a pie chart customisation code example and dig down into each property to better understand how it works.

function(options) {
    options.styleDefaults = {
        colors: ["#ee3124", "#f34733",
        "#f75942", "#fb6950",
        "#fe785f", "#ff866e",
        "#ff947d", "#ffa28d",
        "#ffaf9c", "#ffbdac",
        "#ffcabc", "#ffd7cd",
        "#ffe5dd", "#fff2ee",
        "#ffffff"]
    }
    options.legend = {
    	backgroundColor:"#d3d3d3"
    }
    options.pieCenter = {
    	labelStyle:"font-size:20px; color:black;",
    	label:"Project Cost"
    }
    return options;
}

As previously mentioned, APEX initialisation code expects an extension or overwrite of the default initialisation properties.

In the example above the first line is overwriting the styleDefaults object with a new colour property. As per documentation, this property is an array.

    options.styleDefaults = {
        colors: ["#ee3124", "#f34733",
        "#f75942", "#fb6950",
        "#fe785f", "#ff866e",
        "#ff947d", "#ffa28d",
        "#ffaf9c", "#ffbdac",
        "#ffcabc", "#ffd7cd",
        "#ffe5dd", "#fff2ee",
        "#ffffff"]
    }

The second bit of code refers to the background colour of the legend. In this case, a string is required and is defaulted to NULL.

    options.legend = {
    	backgroundColor:"#d3d3d3"
    }

The last bit is a pie chart specific type definition and controls the inner text of the chart itself.

    options.pieCenter = {
    	labelStyle:"font-size:20px; color:black;",
    	label:"Project Cost"
    }

Apart from the label itself, we can also manipulate the style of it. Please note that there are limited properties supported for the labelStyle.

Setting these options in the chart attributes will generate something similar to this:

Bar Chart Example

Here is another example of the JavaScript Initialisation Function code for a bar chart:

function(options) {

 var myColors = ["#de3b3b", "#e6564f", 
                 "#ed6e63", "#f38378", 
                 "#f8988d", "#fcada3", 
                 "#ffc2b9", "#ffd6d0", 
                 "#ffebe7", "#ffffff"];
    
    options.dataFilter = function( data ) {
        for ( i = 0; i < data.series.length; i++ ) {
            data.series[i].color = myColors [i];
        }
        return data;
    };
    
    options.styleDefaults = {
       barGapRatio:"0.1"
    }
    
    options.legend = {
       backgroundColor:"#e8f1f4",
       symbolWidth:"25",
       borderColor:"#dd5252",
       maxSize:"200",
       symbolHeight:"25"
    }
    
    options.plotArea = {
       backgroundColor:"#e8f1f4",
       borderWidth:"3",
       borderColor:"#dd5252"
    }
    
 return options;
}

When dealing with charts containing distinct series, assigning colours involves using various colours for separate series rather than differentiating colours within the same series. The syntax varies slightly, as demonstrated here:

	var myColors = ["#de3b3b", "#e6564f", 
                 "#ed6e63", "#f38378", 
                 "#f8988d", "#fcada3", 
                 "#ffc2b9", "#ffd6d0", 
                 "#ffebe7", "#ffffff"];
    
    options.dataFilter = function( data ) {
        for ( i = 0; i < data.series.length; i++ ) {
            data.series[i].color = myColors [i];
        }
        return data;
    };

As you can see, the rest of the properties follow the same logic as in the previous pie chart example. For example, here is the result of customisation for the bar chart:

In conclusion

Oracle JET serves as a valuable tool for APEX developers, allowing them to modernise their applications with ease. By leveraging Oracle JET, developers can enhance charts and transform the application interface into an engaging and pleasing experience for clients.

The best part? It should be remarkably straightforward if you have read this far!