Skip to Main Content

Interface: chartRegion

QuickNav

Properties

Methods

chartRegion

The chartRegion interface is used to access the properties and methods of a Chart region. You get access to the chartRegion interface with the apex.region function when passed the regionId (HTML DOM id) of a Chart region.

The chartRegion supports coalescing refresh requests with apex.region.multipleRefresh.

A chartRegion is an APEX wrapper around an Oracle JET data visualization component. You can call methods on the JET component with the chartRegion#call method. When the first argument to call is "option" you can get and set JET component options. JET documents the options as attributes. You have to change hyphen separated attribute names to camelCase options. For example attribute "hover-behavior" becomes option "hoverBehavior". See the JET documentation for details. Tip: You may need to turn on "Show Javascript-only APIs" to see all the options of interest.

Note: The examples that use JET APIs are for illustrative purposes. The JET API may change in the future. Refer to the JET release notes for changes that may impact customizations that you make.

The chart region option type determines which JET component is used. APEX uses the widget interface but JET documents the element. The methods and options available depends on the JET component. The following table gives both the widget name and element that corresponds to the APEX Chart region type.

Mapping from APEX Chart: Type attribute to JET widget and element
Chart Type JET Widget Name JET Element
Gantt ojGantt oj-gantt
Status Meter Gauge ojStatusMeterGauge oj-status-meter-gauge
All other types ojChart oj-chart

For oj-chart, the Chart Type maps directly onto the JET component type property except that Donut is type pie with non-zero inner radius in styleDefaults, Polar is type bar with polar coordinateSystem, Radar is type line with polar coordinateSystem and polygon polarGridShape, and Range is type bar with series data that includes low and high values.

Additional Options

APEX adds the following additional component option. It is set like a JET option in attribute Initialization JavaScript Function but is only used by APEX.

dataFilter

The value is a function that takes a single object data parameter that contains the data for the JET data visualization. The format of the data depends on the specific JET component. See the JET documentation for details. The function can modify the data and must return it.

Example of setting the dataFilter option in a Chart Initialization JavaScript Function attribute. 


function( options ){
    options.dataFilter = function( data ) {
        // modify the data and return it
        return data;
    };
    return options;
}

Extends

Properties

autoRefreshInterval :number

The number of seconds between chart automatic refreshing. The initial value comes from the chart region Automatic Refresh: Interval attribute. See also the chartRegion#startAutoRefresh and chartRegion#stopAutoRefresh methods.

Note: Small values, such as 2 seconds, for this property are discouraged since they may cause serious database performance issues. The interval should be much longer than the time the ajax request to refresh the chart takes. Be sure to take server resources and expected number of clients into consideration.

The value must be 0 (to disable auto refresh) or greater than or equal to 1.

Type:
  • number
Default Value:
  • 0
Example

See the example for chartRegion#startAutoRefresh.

(readonly) element :jQuery

The jQuery object for the region element.

Type:
  • jQuery
Inherited From:
Example

Get option element after initialization.

var value = apex.region( "myRegionId" ).element;

(readonly) lazyLoading :boolean

If false the initial chart data is generated by the server as part of the page and is shown as soon as the chart component is initialized. If true the client will request the initial data using ajax as soon as the chart component is initialized (unless chartRegion#manualLoading is true). The chart component is initialized when it is first visible (takes space in the DOM) and if chartRegion#lazyWhenIrrelevant is true when it is scrolled into view.

This is available as an option property in the chart region Initialization JavaScript Function attribute. The value comes from the chart region Performance: Lazy Loading attribute.

Type:
  • boolean

lazyWhenIrrelevant :boolean

Allows the chart region to be lazy about fetching data initially and during auto refresh (see chartRegion#autoRefreshInterval) if the region is irrelevant to the user according to the browser's CSS "content-visibility" "auto" setting. Typically, regions that are sufficiently outside the scrolling viewport are not relevant.

When true and chartRegion#lazyLoading is true and when the browser renders the page the chart is reasonably far outside the scrolling viewport, the chart will not be initialized (and also will not fetch initial data) until the chart is scrolled into view. When true and auto refresh is happening, the chart will not fetch any data while it is irrelevant (refreshing is paused).

Note: setting to true will add a small delay (depends on browser and page complexity but likely under 100ms) before the chart component is initialized so this should only be set to true for regions likely to be outside the initial viewport. I.e. charts towards the bottom of the page.

When false normal initialization and lazy loading apply.

This is available as an option property in the region Initialization JavaScript Function attribute.

Type:
  • boolean
Default Value:
  • false
Example

On a long page with many regions there is a chart region that is very likely to be outside the scrolling viewport. To delay fetching data for this chart until it is scrolled into view, the following is added to Initialization JavaScript Function. This means that if the user never scrolls the chart into view the chart data is not fetched and the database is not queried, thus reducing load on the server.

function( options ) {
    options.lazyWhenIrrelevant = true;
    return options;
}

(readonly) manualLoading :boolean

If true this region will not automatically fetch the initial data when the chart component is initialized. This allows fetching or otherwise providing the chart data by other means. For example using the apex.region.multipleRefresh function to fetch multiple charts with a single ajax request. If false normal lazy loading happens on page load. Only applies when chartRegion#lazyLoading is true.

This is available as an option property in the chart region Initialization JavaScript Function attribute.

Type:
  • boolean
Default Value:
  • false
Example

In this example a page has 2 chart regions (HTML DOM ids "chart1" and "chart2") with complex SQL queries that take a while to process. Both charts have Lazy Loading on. To reduced load on the server the initial data for each chart is fetched in a single ajax request.

Both charts have Initialization JavaScript Function:
function( options ) {
    options.manualLoading = true;
    return options;
}
Then in a Page Load DA, Execute JavaScript Code action add this code:
apex.region.multipleRefresh(["chart1", "chart2"]);

(readonly) type :string

The chartRegion type is "JetChart".

Type:
  • string
Overrides:

(readonly) widgetName :string

The widget name depends on the chart type. See the table in the chartRegion interface description.

Type:
  • string
Overrides:

Methods

call(pMethod, …args) → {*}

This is used to call methods including getting and setting options on the JET widget associated with the chart region. The type of JET widget depends on the APEX Chart region type. See the table in the chartRegion interface description. See the JET documentation for details on the available methods and options (attributes).

Calling JET component methods before the component is ready will do nothing. However, you can get and set options before the component is ready.

Parameters:
Name Type Attributes Description
pMethod string The string name of the widget method.
args * <repeatable>
 Any number of arguments to be passed to the widget method.
Overrides:
Returns:
The return value depends on the method called.
Type
*
Examples

This example gets the values at the given x and y pixel coordinates.

let values = apex.region( "myLineChart" ).call( "getValuesAt", 90, 80 );
// do something with the values object x, y, and y2 properties.

This example gets the orientation option for the bar chart with HTML DOM id "myBar".

let orientation = apex.region( "myBar" ).call( "option", "orientation" );
// do something with orientation

This example sets the orientation option for the bar chart with HTML DOM id "myBar" to "horizontal".

apex.region( "myBar" ).call( "option", "orientation", "horizontal" );

focus()

Focus the chart.

Overrides:
Example

Focus a chart region with HTML DOM id "myChart".

apex.region( "myChart" ).focus();

isReady() → {boolean}

Returns true if the underlying JET component is initialized and ready to use.

See also chartRegion#whenReady.

Returns:
Type
boolean
Example

This code, which runs when a button is clicked, first checks if the JET chart is ready before setting the horizontal orientation. By checking first it avoids an exception if the user clicks the button before the JET chart has initialized. To keep the user from clicking the button see the example for chartRegion#whenReady.

let areaChart = apex.region( "myAreaChart" );
// make sure chart is ready, to avoid an exception (Another way is to use the call
// method which allows setting options before the component is ready.)
if ( areaChart.isReady() ) {
    areaChart.widget().ojChart( "option", "orientation", "horizontal" );
}
// otherwise do nothing. The user will likely try to click the button again

off(events, …args)

Removes an event handler from the JET component element associated with this region. See the JET documentation for the events that the JET component supports.

See also chartRegion#on.

Parameters:
Name Type Attributes Description
events One or more space-separated event types and optional namespaces as defined by the jQuery off method.
args * <repeatable>
 Other arguments to be passed to the widget's jQuery object off method such as selector, data, and handler.
Overrides:
Example

This removes the ojviewportchange event handler.

apex.region( "myStockChart" ).off( "ojviewportchange" );

on(events, …args)

Attaches an event handler to the JET component element associated with this region. See the JET documentation for the events that the JET component supports.

See also chartRegion#off.

Parameters:
Name Type Attributes Description
events One or more space-separated event types and optional namespaces as defined by the jQuery on method.
args * <repeatable>
 Other arguments to be passed to the widget's jQuery object on method such as selector, data, and handler.
Overrides:
Example

On a stock chart that supports zoom and scroll this will handle viewport changes as the user zooms or scrolls.

apex.region( "myStockChart" ).on( "ojviewportchange", function( event, data ) {
    console.log( "viewport changed", data.xMax, data.xMin );
    // do something in response to viewport change event
} );

refresh() → {Promise|null}

Refresh the data visualization with new data from the server. Does nothing if the chart control is not yet initialized. (See chartRegion#whenReady.)

When data is fetched from the server this will trigger the apex.event:apexbeforerefresh event before the data is refreshed and the apex.event:apexafterrefresh event after the data is refreshed.

Overrides:
Returns:
A jQuery promise for the fetch request or null if called before the chart control is initialized.
Type
Promise | null
Example

Refresh a chart region with HTML DOM id "myChart". The server will return the current data for the chart region.

apex.region( "myChart" ).refresh();

refreshView()

Refreshes the data visualization without fetching new data from the server. Use this for example if the underlying series data on the client side has been changed programmatically.

Example

This example of a line chart doubles each of the first series values and then refreshes the line chart.

let s1 = apex.region( "myLineChart" ).call( "option", "series" )[0];
s1.items.forEach( item => {
    item.value = item.value * 2;
    item.label = item.label * 2;
} );
apex.region( "myLineChart" ).refreshView();

startAutoRefresh()

Starts automatically refreshing this chart every chartRegion#autoRefreshInterval seconds. The autoRefreshInterval must not be 0. The refreshing will pause if the browser window or tab or the chart region is hidden and will resume once it is visible again.

The refreshing can be stopped with chartRegion#stopAutoRefresh.

Example

Refresh the chart every 5 minutes while it is visible.

let chartRegion = apex.region( "myLineChart" );
chartRegion.autoRefreshInterval = 300; // 5 minutes
chartRegion.startAutoRefresh();

stopAutoRefresh()

Stops automatically refreshing this chart if it was previously started with chartRegion#startAutoRefresh.

Example

Stop refreshing the chart.

apex.region( "myLineChart" ).stopAutoRefresh();

whenReady() → {Promise}

Returns a promise that resolves when the underlying JET component is initialized and ready to use. Note that a chartRegion is not initialized until it is first visible and the JET library has loaded. The data may not yet be loaded.

See also chartRegion#isReady.

Returns:
Type
Promise
Example

In this example a button with HTML DOM id "orientationButton" is initially disabled (with button attribute Show as Disabled = On or Custom Attribute = disabled). Then in a Page Load dynamic action this code will enable the button. This is another way to ensure a user clicking on a button as soon as the page loads doesn't cause an exception when that button calls a JET component API. Compare with chartRegion#isReady example.

apex.region("areaChart").whenReady().then( () => {
    // now that areaChart is ready enable the button that sets the orientation
    $( "#orientationButton" ).removeAttr( "disabled" );
} );

widget() → {jQuery}

Returns the JET widget element associated with the chart region. The type of JET widget depends on the APEX Chart region type. See the table in the chartRegion interface description. If the intent is to use the widget interface it is better to use the chartRegion#call method.

Overrides:
Returns:
the jQuery element for the JET widget.
Type
jQuery