chartoptions

note

This article is about the chartoptions UDB event handler.

chartoptions

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

Event	Applies to	Occurs when
chartoptions	Chart controls (ChartControl)	Before the chart's rendering options 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. It fires once when the chart object is first constructed (for charts that do not use ChartDataControl child columns, right before new ApexCharts(...) is called), and again on every subsequent render pass, right before the accumulated options object is handed to chartObject.updateOptions().

Purpose

You can use this event to fine-tune or completely override the options object that ApexCharts uses to render the chart, for example to change colors, axis titles, tooltips, or any other ApexCharts chart option that Web Designer does not expose as a property.

How to use

Find or create an Event Listener object with Event Type = chartoptions. 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

options.chartOptions.colors = [ '#dd0000' ];
options.chartOptions.xaxis = { title: { text: 'Quarter' } };

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*   ::=  {
     mode:  *mode*,
     chartOptions:   *chartOptions*
}

*mode*   ::=  { ['append'] | 'replace' }

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*

mode is a string that determines how chartOptions, once your handler returns, is combined with the chart options that USoft has already prepared. The default value is 'append', which means that the properties you set on chartOptions are merged (deep-extended) into the options that ApexCharts will use, leaving all other, unmentioned options unchanged. Set mode to 'replace' to have your chartOptions object completely replace the prepared options object instead of being merged into it.

chartOptions is the (mutable) options object that will be passed to ApexCharts. It is prefilled by USoft with the chart options derived from the control's Web Designer properties (chart type, size, title, legend, axis titles, and so on). Modify its properties in your handler to customize how the chart is rendered; when mode is 'append', only the properties you actually set are applied on top of the prepared options, so you do not need to repeat properties you do not want to change.