LoadingData

Loading data

In Chartbreaker, data is added in the form of timeseries via the BG.charts.Controller.addTimeSeries method. The method expects an alphanumeric identifer to reference a specific timeseries. This identifier is then used to create an instance of a so-called 'data loader' (which implements BG.charts.IDataLoader). To add a timeseries backed by the Custom data loader to the chart, simply call:

controller.addTimeSeries('Custom(arg1,arg2)');

All arguments in the identifier (e.g. "arg1" and "arg2") are forwarded to the constructor of the data loader class.

Of course, the data loader must first be created before it can be used by Chartbreaker. Simply create a class that implements the BG.charts.IDataLoader interface. The following shows a minimal example:

/*
* resolution (time per data point) is supplied by chartbreaker
* additional arguments are forwarded directly from the identifier (e.g. "Custom(arg1,arg2)")
*/
class CustomLoader {
    constructor(resolution, arg1, arg2) {};

    /**
    * called to load the actual
    */
    load(cb, pushCb, invalidateCb, context) {

        /* Get any historic data and store them in an array of number arrays.
         * Each entry must contain 6 values in this particular order:
         * Timestamp in milliseconds, close, open, high, low, volume
         * Data _should_ be pre-aggregated for the resolution passed to the constructor
         * If it is not, Chartbreaker will try to automatically group/merge it
         */

        var values = [
            [1009926000000, 102, 98, 103, 97, 0]
            // ...
        ];

        /* To support conversions between resolutions, a timezone, start and
         * end time (in milliseconds since beginning of a day) must be provided.
         */

        const metadata = {
            timezone: 'Europe/Berlin',
            startTime: 3600*9*1000, // 09:00
            endTime: 3600*18*1000 // 18:00
        };

        /* An Error can be given as first argument.
         */

        cb(null, metadata, values);

}

The next step is to register the loader as a plugin with Chartbreaker. This is done via BG.charts.setClazz; the method receives an object with all required options, like supported resolutions and the type identifier of the loader. 'type' defines the identifier used for the time series, which can then be added to a chart via the Controller (see previous section).

BG.charts.setClazz({
    clazzType: 'loader',
    type: 'Custom',
    resolutions: [BG.charts.ESpans.MINUTE],
    clazz: CustomLoader
});

The resolution represents the timespan of a single data point. For each supported resolution and timeseries parameters, a seperate instance of the loader is created. Chartbreaker will automatically try to group data on the fly for resolutions that are not supported by a loader. E.g., if you want to display a 1-hour chart, but the loader only supports a resolution of 1 minute (such as in this example), Chartbreaker will simply create a 1-minute loader, and then merge the resultant data.

Realtime Data Updates

The load method of the loader will be given a push callback. This callback can be used to provide realtime data updates to chart. How this data is retrieved is up to the loader (e.g. WebSocket or polling).

Once new values become available, they can be forwarded to the chart as follows:

pushCb({
    'time':    Date.now(),        // unix timestamp in milliseconds
    'quote':   123.45,            // new data value

    'volume':  0,                 // volume for this tick (optional, will be summed up automatically)
    'prev':    122.0              // close of previous day (optional, just needs to be provided once for displaying changes)
});

Alternatively, you can also supply high,low,open, and close to the callback instead of quote. This could be used for example if you do not want to push each tick separately and instead just update charts periodically.