chartdata

note

This article is about the chartdata UDB event handler.

chartdata

The chartdata event may be called from web pages developed in Web Designer and processed by a USoft page engine service.

Event	Applies to	Occurs when
chartdata	Chart controls (ChartControl)	Before the chart's series data and labels are applied to the underlying ApexCharts chart object

This event is triggered on a Chart control's own element (control.$el) by the chart-rendering logic (ApexChartsLib.render()) that a ChartControl instance (defined in controls/chart-control.js, a subclass of DataControl) uses internally, right before the chart's series and labels are handed to chartObject.updateOptions(). It fires on every render pass. This event is especially relevant for a Chart control that is not bound to a data source (no Data source item set, and no ChartDataControl child columns): for such a chart, USoft cannot derive any series data by itself, so a chartdata event handler is the mechanism you use to supply the chart's actual data and labels.

Purpose

You can use this event to supply or override the data (series values) and labels that are rendered on the chart, most importantly for charts that get their data from something other than a bound data source, for example computed values, an external call, or values assembled from several data sources.

How to use

Find or create an Event Listener object with Event Type = chartdata. Event Listeners are in the Web Designer Controls catalog:

Insert the event listener into the Chart control. Insert a callClientScript action into the event listener. Use this action's Script property to code the behaviour that you want to see when the event occurs.

You are implicitly associating the event with an event handler function. This function has an options parameter. For available options, see the Options section at the end of this help topic:

function(*event*, *options*){ ... }

Or you can create the event handler more explicitly by attaching a jQuery handler on the control's element.

Example

// supply the data for a chart that has no data source of its own
options.chartData = [
  { name: 'Revenue', data: [ 30, 45, 28, 60 ] }
];
options.chartLabels = [ 'Q1', 'Q2', 'Q3', 'Q4' ];

Options

When the event occurs, the following event handler function is called. You can use this function's options parameter in your event scripting.

function( *event*, *options* )

*event*     ::=  jQuery.Event
*options*   ::=  *event-options*

*event-options*   ::=  {
     chartData:    *chartData*,
     chartLabels:  *chartLabels*
}

Event contains the run-time details of the triggered event, of the event type stated above.

This syntax means that you can access an option by scripting

options.*option*

chartData is the (mutable) array of series objects that ApexCharts will render. Each entry is normally an object with a name and a data array of values, in the shape that ApexCharts expects for the control's chart type. Assign or modify this array in your handler to supply or change the data points that are plotted.

chartLabels is the (mutable) array of category labels (or, for date/time axes, the axis values) that correspond to the data points in chartData. Assign or modify this array in your handler to supply or change the labels shown along the chart's axis (or, for charts such as pie or donut charts, the slice labels).