JET Charts in Application Express 5.1

One of the most-mentioned new features in Application Express 5.1 are the new charts based on Oracle JET. JET is the abbreviation for Javascript Extension Toolkit. It is targeted at intermediate to advanced JavaScript developers working on client-side applications. It's a collection of open source JavaScript libraries along with a set of Oracle contributed JavaScript libraries that make it as simple and efficient as possible to build applications that consume and interact with Oracle products and services, especially Oracle Cloud services.

Such applications are often one page apps, which are loaded into the browser only once and all the following functionality and server communication is done with javascript. The Oracle JET Cookbook contains many examples showcasing how to use Oracle JET.

Oracle JET - home page

Oracle JET contains a lot of components for data visualization - and these are the foundation for the new chart types in Application Express 5.1. Note that not all JET visualizations are available as Application Express charts (at least at this time).

Oracle JET - data visualizations

JET charts in Application Express

Application Express 5.1 contains the whole distribution of Oracle JET 2.0.2. At this time, only Charts are available as declarative APEX components. Other JET functions and components are available to APEX developers as well, but javascript must be used for this. Because of dependencies of Oracle JET, and Application Express, to the jQuery library, Oracle JET cannot be replaced with a newer version in Application Express 5.1.

When creating a new chart in Application Express 5.1, Oracle JET is not obviously visible to the developer; just the list of available chart types indicates, that something major has changed.

Chart types in Application Express 5.1

Gantt and Map charts don't use Oracle JET in Application 5.1; as in earlier versions, these are driven by the AnyChart engine.

Creating a chart works similar to earlier Application Express versions. A chart is still driven by a SQL query as the data source and configured using Page Designer. Unlike previous versions, specific SQL query syntax is not required any more: Any SQL query (even select * from emp) can be used.

With Page Designer, in Chart Attributes, SQL result columns are then mapped to chart attributes like value, label or link. Basic chart types (like Bar or Line) need at least two columns; other types might need more. The chart attributes in Page Designer indeed look different (and we have a lot more attributes), just because Oracle JET is different to the AnyChart engine used in the previous APEX versions.

All Application Express charts based on Oracle JET are responsive and accessible - so they adjust to the actual screen size, can be used with the keyboard or being processed by screen readers. Beyond that, Oracle JET charts can be automatically refreshed in regular intervals - which is important for dashboard or portal pages.

Application Express 5.1 charts are responsive

To cover all chart types, with their individual configuration options, would go way beyond the scope of a how to document like this one. The best recommendation for a developer is to try it out themselves. With creating charts on the omnipresent EMP and DEPT tables, the developer gets pretty far. For those who want to see some results without doing anything, Application Express contains the Sample Charts packaged application - in that application all JET charts (and not only these) are available at least once. The Sample Charts can application is also directly available on apex.oracle.com/charts.

Packaged application "Sample Charts" - Overview

Packaged application "Sample Charts" - bubble charts

Packaged application "Sample Charts" - polar charts

Time axis support in Oracle JET charts is very interesting, when chart labels are mapped to DATE or TIMESTAMP columns. The charts X axis can then be declaratively set as a time axis, by setting the Time Axis Type chart attribute to Enabled. Labels will then be correctly rendered as readable dates. The other options of the Time Axis Type, Skip Gaps or Mixed frequency, allow to control the charts behavior for data gaps or for multiple data series with values for different data points.

Time axis support in Oracle JET Charts

Mixed frequency is a very powerful chart attribute. Normally, when the label is NUMBER or VARCHAR2 data type, the developer must make sure that all series of a multi-series chart return values for the same data points. If necessary, they have to provide additional NULL values for the missing data points using outer joins or other SQL functions. However, for DATE or TIMESTAMP labels, the Mixed frequency functionality takes care of this: Oracle JET will correctly render the data points into the chart timeline. The Sample Charts application showcases this on the Combination page - section Combination Chart (Regular v Mixed Frequency Time Axis).

Time axis support in Oracle JET Charts: Mixed frequency support

Chart upgrade from previous Application Express versions to 5.1

In previous releases of Application Express, the declarative charting solution was based on AnyChart charts. For the Gantt and Map charts, this is still true in Application Express 5.1 - that may change in a future version.

The AnyChart engine is still contained in Application Express 5.1 - and that is needed for exactly those applications, which have been created in a previous release and which are upgraded to or imported into a 5.1 instance. The reason is that ...

... when Application Express instances are upgraded or applications are imported from a previous release, these applications work as they worked in the previous release. Functionality does not change.

Thus, an AnyChart chart within an APEX 5.0 application, will still be an AnyChart chart after the instance has been upgraded, or the application has been imported into APEX 5.1. No automatic migration to Oracle JET will happen. All charts will look as they looked in the previous APEX version (slight differences in the following screenshots result from differences in the table data).

Charts (based on AnyChart) in Application Express 5.0

Charts (based on AnyChart) in Application Express 5.1

To convert your existing AnyChart charts to Oracle JET charts, we have to perform an Application Upgrade. For that, in the Application Builder navigate to the application, then to Utilities and then choose Upgrade Application.

"Upgrade Application" - within Application Utilities

In the Application Upgrade area, you will see the Upgrade AnyChart Charts to Oracle JET Charts upgrade type together with the amount of Candidate Objects.

We can upgrade four AnyChart chart regions to Oracle JET charts"

Click on the amount of Candidate Objects in the right report column (in this example: "4"). Then you will see the individual chart regions. Check the regions you want to have upgraded to Oracle JET charts. Clicking the Upgrade button finally migrates the AnyChart charts to Oracle JET charts.

Choose the chart regions which are to be upgraded to Oracle JET charts

The chart regions have been upgraded to Oracle JET charts

The chart regions have been upgraded to Oracle JET charts

This automatic migration supports all chart regions based on AnyChart which have only declarative configuration. As soon as the Custom XML attribute has been used in order to configure the chart with AnyChart XML directly, the region cannot be upgraded any more. The following screenshot shows a line chart from APEX 5.0 - the line width of that chart has been customized using the Custom XML attribute.

AnyChart chart region, customized with "Custom XML"

Immediately after importing the application to the APEX 5.1 environment, the chart is still driven by AnyChart - it looks as it looked in the previous APEX version. To upgrade to JET charts, we - again - navigate to the Application Upgrade section. But now we see one less Candidate Object: the chart region using Custom XML cannot be migrated, so the developer has to change that to a JET chart manually.

Chart regions using "Custom XML" cannot be migrated to Oracle JET charts

Customize Oracle JET charts with Javascript code

APEX developers can also work with Oracle JET charts using the Javascript API directly; to explore the various configuration options it's best to consult the ojChart description within the Oracle JET documentation.

Javascript documentation for the Oracle JET object "ojChart"

The Javascript API plays nicely together with Application Express Dynamic Actions. Upon button click, the orientation of a bar or line chart can be changed from horizontal to vertical or vice-versa. To achieve that, make sure that your chart region has a Static ID on order to reference it within Javascript code. Then create the button and a dynamic action. On the button Click event, execute the following Javascript code:

// changes chart orientation to vertical
$("#{chart-region-static-id}_jet").ojChart({orientation: 'vertical'});

The Sample Charts application shows this nicely on the Area page.

Changing chart orientation by clicking an APEX button

Another case for using the Javascript API is to control chart behavior beyond the attributes offered by Page Designer. To do that, open the chart region attributes in Page Designer, navigate to the Advanced section and look up Javascript Code.

Customize an Oracle JET charts with "Javascript Code" in the "Advanced" section

This attribute expects a javascript function. Application Express will pass an Oracle JET configuration object to that function. The function changes and returns that configuration object. The implementation is completely up to the APEX developer. Thus the whole Oracle JET javascript functionality can be applied to an Oracle JET chart region in Application Express.

To change the line width for a line chart region, we could use the styleDefaults.lineWidth attribute - but wait a moment: For this, we now have a declarative attribute in 5.1 - and we should prefer declarative attributes whenever we can. So, before diving into Javascript coding, always check whether Page Designer provides a declarative attribute for your purpose.

For the scope of this how to document, we will use Javascript to change the Marker within the line chart region. There are declarative attributes to determine whether we have a marker (or not) and which shape is to be used. With Javascript, we can do a bit more: We want to have a different color and a different size. To achieve that, in Page Designer, navigate to Advanced - Javascript Code and add the following Javascript code.

function( o ) {
    o.styleDefaults.markerDisplayed = "on";
    o.styleDefaults.markerShape     = "human";
    o.styleDefaults.markerSize      = 15;
    o.styleDefaults.markerColor     = "red";
    return o;
}

Customizing an Oracle JET chart region with Javascript

The result will look similar to the following.

The Oracle JET chart region has been customized with Javascript

Using Javascript code, the APEX developer can leverage all power of the Oracle JET javascript API. However, always keep in mind, that the strength of Application Express is declarative development and the Application Express repository. When working with Javascript, APEX does not know about your chart configuration; you cannot use the power of the APEX repository for these charts. So, whenever you can, use the declarative features of Application Express.

Back to the Oracle Application Express blog