Skip to main content

Custom Chart Options

Echarts has a large number of configuration options. This provides a lot of power and yet it can be very daunting to master all of these options. SQL Frames provides a unified low-code API to support various types of charts. This is done by automatically deriving many of the settings with a good out of the box experience. However, there will be need for making the charts configured further to meet specific styling requirements. SQL Frames provides several ways of doing them and these are discussed below.

Chart components​

DataSeries​

In SQL Frames all the charts are plotted by providing their data from a DataFrame. The data series of the charts are the fields of the DataFrames. Most API have the pattern of

/* 
(x-axis,y-axis)
(radius-axis,angle-axis)
(x-axis,parallell-axis)
*/
chart.chartType(axis-field|axis-fields,axis-field|axis-fields);

axis-fields := axis-fields-term y-axis-fields
axis-fields-term := [] | 
					axis-field | 
					[axis-field ...] /* this is for stacked charts */

Each axis field maps to a DataSeries object. Once a chart is constructed, these DataSeries objects can be obtained using chart.xseries and chart.yseries arrays which are flattened even though the chart arguments are nested in case of start charts.

One or more (typically two) DataSeries result in a series and axis (xAxis, yAxis and so on) nodes of the final Echarts options JSON object.

DataFrameChart​

The DataFrameChart creates many series by the cartesian product of the first and second axis field arguments. That is chart.line([quarter,month],['amount1',['amount2','amount3']) results in creating 6 series. The quarter and month DataSeries can be accessed using chart.xseries[i] and chart.yseries[i].

Static Grids​

It is possible to display all the series in a single chart or they can be placed side-by-side as a grid. These are series on the static grid, that is the number of chart series is pre-determined based on the arguments to the chart.

Dynamic Grids​

It is also possible to create dynamic grids based on data. The number of the final chart series is dependent on data.

Coordinate Systems​

ECharts has several cooridnate systems such as cartesian coordinate system and polar coordinate system. Further each Coordinate System has 1 or more axis. These are logical objects and have no options available for configuration.

Axis​

The axis data is created from the DataSeries. Multiple DataSeries might be sharing the same axis. For example a chart with two lines will have both y-axis DataSeries sharing the same y-axis. However, it is possible to setup multiple axis if desired and by default first y-axis is on the left and the second one on the right and first x-axis at the bottom and the second x-axis at the top.

DataSet​

Based on the DataSeries information, the DataFrameChart fetches data from the DataFrame and then further transforms into DataSets suitable for the ECharts options.

Configuraton Levels​

Series Option Fields​

ECharts has several options for each series and the DataSeries only exposes just a handful of common options. For example, lineStyle of smooth can be achieved using

chart.xseries[i].smooth = true;
// or
chart.yseries[i].smooth = true;

Series Options JSON​

When there is no series.field available for configuring the individual fields then the entire JSON can be configured. This can be done using

chart.xseries[i].options = { ... };
// or
chart.yseries[i].options = { ... };

SQL Frames first derives the series options from the rest of the configuraiton and then merges these custom options (Object.assign(derivedOptions,xs.options,ys.options)) from both the xseries and yseries options.

Axis Options JSON​

Axis level options can be customized using

chart.xseries[i].axisOptions = { ... };
// or
chart.yseries[i].axisOptions = { ... };

SQL Frames first derives the axis otpions from the rest of the configuration and then merges these custom options (Object.assign(derivedOptions,s.axisOptions)).

Chart Options​

Legend Options​

Usg chart.legendOptions which are merged with default options.

chart.icustomize function​

It is possible to get full control of the eCharts options created by SQL Frames and either tweak it or return a completely new options object based on it. Since the above options rely on merging of the JSON nodes, customizing at deeper levels of the JSON requires using this option.

chart.icustomize = (options) => { return options; } // no customization

Best Practices​

Below are some guidelines to customizing

  • Customize as little as possible.
  • Customize at the most specific levels if possible.
  • Explicitly set options to undefined if those options are in conflict with other options being customized. Otherwise, the merged JSON will have both options and may not work as expected.
  • Always make sure the custom options work under various data sets.
  • Avoid customizing options related to data. Data should always come from the DataFrame itself.
  • Avoid customizing static and dynamic grid charts as their layout is based on some default assumptions.