Docs

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Docs

Charts 2 to Charts 3 Migration Guide

Introduction

Most of Vaadin Charts 3 API is compatible with Vaadin Charts 2.x. It can thus be used as a drop-in replacement for any 2.x version with some minor fixes. The objective of this document is to make the transition from Vaadin Charts 2.x to Vaadin Charts 3.x easier.

Note for non-Maven Users

Vaadin Charts 3 was restructured and now has a new JAR: vaadin-charts-model-VERSION.jar, which includes the model classes. If dependencies are managed manually the vaadin-charts-model-VERSION.jar can be found in addon/lib/ folder of the ZIP file downloaded from Vaadin Directory and needs to be added to the project.

Timeline

One of the big features of Vaadin Charts 3 for Java is dropping the old Timeline component. The widgeset needs to be updated because the timeline was removed. To update the widgetset, run mvn vaadin:update-widgetset or delete a reference to the timeline widgetset in a project gwt.xml file. Vaadin Charts 3 introduced the new timeline mode that can be used in regular charts with time-typed X axis. You can find out more about this feature in "Timeline section".

Changes in Abstract Classes

Axis

Axis has three properties, min, max, and axisIndex, common for all axes. All other properties were moved to concrete implementations. Use concrete implementations (XAxis, YAxis, ZAxis) instead of Axis.

PlotOptions

Some properties in AbstractPlotOptions in Vaadin Charts 2.x were not supported by all the subclasses. For example, setting animation in PlotOptionsPyramid had no effect. In Vaadin Charts 3, properties from AbstractPlotOptions were moved to concrete implementations, that support the properties. In Vaadin Charts 3, instead of using AbstractPlotOptions, use a specific implementation, such as PlotOptionsArea, PlotOptionsBar, etc.

All the chart types in Vaadin Charts 3 are divided into several groups with common properties. These groups are presented as abstract classes, that allow to use polymorphism for setting common properties for specific implementations. For example, to set the same lineWidth for PlotOptionsLine and PlotOptionsSpline use PointOptions.

private void setCommonProperties(PointOptions options) {
    options.setLineWidth(5);
    options.setColor(SolidColor.RED);
    options.setAnimation(false);
}
...
PlotOptionsSpline plotOptions=new PlotOptionsSpline();
PlotOptionsLine plotOptions2=new PlotOptionsLine();
setCommonProperties(plotOptions);
setCommonProperties(plotOptions2);
series.setPlotOptions(plotOptions);
series2.setPlotOptions(plotOptions2);

This is the list of abstract classes with their specific implementations:

  • AreaOptions → PlotOptionsArea, PlotOptionsArearange, PlotOptionsAreaspline, PlotOptionsAreasplinerange

  • ColumnOptions → PlotOptionsBar, PlotOptionsColumn, PlotOptionsColumnrange

  • GaugeOptions → PlotOptionsGauge, PlotOptionsSolidgauge

  • PointOptions → PlotOptionsLine, PlotOptionsSpline, PlotOptionsScatter

  • PyramidOptions → PlotOptionsPyramid, PlotOptionsFunnel

  • OhlcOptions → PlotOptionsOhlc, PlotOptionsCandlestick

In other words, to set common properties for PlotOptionsBar and PlotOptionsColumn you can use ColumnOptions, for PlotOptionsArea and PlotOptionsArearange you can use AreaOptions, and so on.

Changes in Class Names

PlotOptions

Apart from the new plot options for the new chart types (PlotOptionsCandlestick, PlotOptionsFlags, and PlotOptionsOhlc), there has been the following changes in the names of the existing plot options:

  • PlotOptionsAreaRange → PlotOptionsArearange

  • PlotOptionsAreaSpline → PlotOptionsAreaspline

  • PlotOptionsAreaSplineRange → PlotOptionsAreasplinerange

  • PlotOptionsColumnRange → PlotOptionsColumnrange

  • PlotOptionsHeatMap → PlotOptionsHeatmap

  • PlotOptionsSolidGauge → PlotOptionsSolidgauge

  • PlotOptionsTreeMap → PlotOptionsTreemap

Labels

The Labels class was used in:

  • PlotOptions as data labels

  • XAxis and YAxis as labels

  • DataSeriesItem as data labels

  • TreeMapLevel as data labels

Given that not all Labels properties were useful in all the places where it was used, the class was split and the following classes have been created:

  • DataLabelsFunnel used in PlotOptionsFunnel and PlotOptionsPyramid

  • DataLabelsRange used in PlotOptionsArearange, PlotOptionsAreasplinerange and PlotOptionsColumnrange

  • DataLabels used in the rest of plot options implementations

  • Labels used in XAxis and YAxis

  • Label used in Crosshair, PlotBand and Plotline

Tooltips

Tooltip was split into two classes: Tooltip and SeriesTooltip. The Tooltip class contains all the properties to configure tooltips in a chart. These properties are used in every series in the chart. The SeriesTooltip class is a subset of tooltip properties which can only be defined on the series level. For example, useHTML can only be defined on the chart level. Tooltip should be used in the chart configuration object. SeriesTooltip should be used in plot options implementations: PlotOptionsArea, PlotOptionsBar, etc.

Other

  • MarkerStates → States

  • State → Hover and Select

  • CrosshairStyle → Crosshair

  • TreeMapLevel → Level

  • CreditPosition → Position

  • FramePanel → Back, Bottom, and Side

Changes in Method Names

Align Properties

The align property accepts values defined in the HorizontalAlign enum in all cases with the exception of AxisTitle. In the AxisTitle class, the align property accepts values defined in the VerticalAlign enum.

Color Properties

Setters of color properties now accept a SolidColor or GradientColor parameter. A setter that accepts a String parameter was removed. Instead of it use a SolidColor constructor.

plotOptions.setFillColor(new SolidColor("#ff0000"));

Crosshair

The crosshair definitions have been moved to the axis object for a better separation from the tooltip. The setCrosshairs(CrosshairStyle) method in Tooltip class is now setCrosshair(Crosshair) method in XAxis and YAxis classes.

Plot Options

The API to configure plot options in Configuration class has changed.

Renamed methods:

  • setPlotOptions() → addPlotOptions()

  • getAllPlotOptions() → getPlotOptions()

New methods:

  • setPlotOptions(AbstractPlotOptions …​)

  • getPlotOptions(ChartType)

The previous setPlotOptions() method added new plot options to existing ones but the new method will reset the plot options.

Size related properties

In order to follow Vaadin Framework standards, properties related to size (size, innerRadius, outerRadius, thickness, whiskerLength, and so forth) now have two different setters. One of the setters has a single String parameter. The other setter has a float and a Unit enum parameter. The setSizeAsPercentage() method was removed.

As shown in the following example, a percentage width can be defined using both setters

PlotOptionsPyramid options = new PlotOptionsPyramid();

// Old setter
// options.setWidthAsPercentage(70);

// Using float and Unit
options.setWidth(70, Unit.PERCENTAGE);

// Using String setter
options.setWidth("70%");

  • In Pane, setCenterXY(String, String) is now setCenter(String, String). The method setCenterXY(Number, Number) was removed.

  • In PlotOptionsFunnel, PlotOptionsPie, and PlotOptionsPyramid, the method setCenter(Number, Number) was removed. Use setCenter(Number, Number) instead.

Other

  • In PlotOptionsLine, setStepType() is now setStep().

  • In XAxis, setShowLastTickLabel() is now setShowLastLabel().

  • In YAxis, setMinorTickInterval(Number) was removed, use setMinorTickInterval(String) instead. The setMinTickInterval() method was added. Be aware of mixing up these two methods. The minorTickInterval property specifies the interval between minor ticks, while minTickInterval specifies the minimum tick interval allowed in axis values.

  • In YAxis, Stop is not an inner class anymore.

Example

Original Charts 2 configuration

private Chart getChart() {
    Chart chart = new Chart();

    Configuration config = chart.getConfiguration();
    config.setTitle("Charts migration");
    config.getTitle().setHorizontalAlign(HorizontalAlign.LEFT);

    config.getTooltip().setCrosshairs(
    new CrosshairStyle(10, SolidColor.BLACK, DashStyle.SOLID, 0),
    new CrosshairStyle(5, "#880000", DashStyle.DOT, 1));

    config.getLegend().setEnabled(false);
    config.getTooltip().setEnabled(false);

    ListSeries ls = new ListSeries();
    ls.setName("Data");
    ls.setData(29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4,
            194.1, 95.6, 54.4);
    ls.setPlotOptions(new PlotOptionsAreaSpline());
    ls.getPlotOptions().setColor(SolidColor.BURLYWOOD);
    ls.getPlotOptions().setDataLabels(new Labels(false));
    config.setSeries(ls);
    return chart;
}

Changes needed

Horizontal alignment of the title should now be set using the setAlign() method.

CrosshairStyle is now Crosshair and one instance should be set in both XAxis and YAxis.

PlotOptionsAreaSpline is now PlotOptionsAreaspline.

DataLabels should be used in the setDataLabels() method instead of the Labels class.

Resulting Charts 3 Configuration

private Chart getChart() {
    Chart chart = new Chart();

    Configuration config = chart.getConfiguration();
    config.setTitle("Charts migration");
    config.getTitle().setAlign(HorizontalAlign.LEFT);

    Crosshair xCrossHair = new Crosshair();
    xCrossHair.setColor(SolidColor.BLACK);
    xCrossHair.setDashStyle(DashStyle.SOLID);
    xCrossHair.setWidth(10);
    xCrossHair.setZIndex(0);
    config.getxAxis().setCrosshair(xCrossHair);

    Crosshair yCrossHair = new Crosshair();
    yCrossHair.setColor(new SolidColor("#880000"));
    yCrossHair.setDashStyle(DashStyle.DOT);
    yCrossHair.setWidth(5);
    yCrossHair.setZIndex(1);
    config.getyAxis().setCrosshair(yCrossHair);

    config.getLegend().setEnabled(false);
    config.getTooltip().setEnabled(false);

    ListSeries ls = new ListSeries();
    ls.setName("Data");
    ls.setData(29.9, 71.5, 106.4, 129.2, 144.0, 176.0, 135.6, 148.5, 216.4,
            194.1, 95.6, 54.4);
    PlotOptionsAreaspline plotOptions = new PlotOptionsAreaspline();
    plotOptions.setColor(SolidColor.BURLYWOOD);
    plotOptions.setDataLabels(new DataLabels(false));
    ls.setPlotOptions(plotOptions);
    config.setSeries(ls);

    return chart;
}