Series Overview

Progress NativeScript UI Chart comes with a bunch of series suitable for different types of data. There are two main chart types: Cartesian and Pie. Each of these chart types requires corresponding series types to be able to visualize the data. For RadCartesianChart you need to use CartesianSeries, and for RadPieChart you need to use PieSeries. CartesianSeries are represented by two main series types: scatter and categorical.

All series expose the following properties:

  • showLabels - determines whether labels are shown for each data point
  • legendTitle - determines the title which will be displayed in the legend for the current series
  • valueProperty - determines the name of the property on the source object that will provide the value used to plot the object in the chart
  • items - used to bind the series with a source of data items
  • selectionMode - responsible for the selection mode of the series. The values are:
    • None - the series cannot be selected
    • NotSet - series selection is not set and the series selection mode set to chart will be used.
    • Series - the whole series will be selected
    • DataPoint - the touched data point will be selected only
    • DataPointMultiple - multiple data point will be selected
  • labelStyle - property of type PointLabelsStyle defining the style of the point labels

Cartesian Series

The CartesianSeries draw the data from the source in a Cartesian Coordinate System. Examples of Cartesian Series are:

All cartesian series can be divided into two groups depending on the axes they can play with:

  • Linear series
  • Categorical series

Categorical Series require a combination of a linear axis and a categorical axis, whereas Linear Series require both axes to be linear. In other words, Categorical Series plot the X or the Y value of the data object on a categorical axis, i.e. they fit the X or Y value into a particular category. The Linear Series plot the data objects on two linear axes, i.e. both X and Y are values that belong to a given linear range.

As CartesianSeries all categorical series share the base cartesian series API and provide a couple of additional properties needed for their proper initialization. The following properties are part of this object and are needed for correctly setting up a categorical chart:

  • categoryProperty - defines the name of the property on the data object which will be used to plot the object into the right category
  • stackMode - defines how separate series are combined within a single chart

Here's a simple scenario using Bar series. In our NativeScript application we define an object that exposes a collection which we will use as a data source for our chart. The collection is exposed by the categoricalSource property. We additionally define a page with a chart in it and set the bindingContext of the page to point to an instance of a data-model object:

get categoricalSource() {
    return [
        { Country: "Germany", Amount: 15, SecondVal: 14, ThirdVal: 24 },
        { Country: "France", Amount: 13, SecondVal: 23, ThirdVal: 25 },
        { Country: "Bulgaria", Amount: 24, SecondVal: 17, ThirdVal: 23 },
        { Country: "Spain", Amount: 11, SecondVal: 19, ThirdVal: 24 },
        { Country: "USA", Amount: 18, SecondVal: 8, ThirdVal: 21 }
    ]
}

In our page definition, we set the bindingContext of the page to point to a CategoricalDataModel object:

import dataModelModule = require("../../data-models/categorical-data-model");

export function onPageLoaded(args){
    var page = args.object;
    page.bindingContext = new dataModelModule.CategoricalDataModel();
}

And in the XML definition of the page we put an instance of RadCartesianChart, define the BarSeries and bind them to the categoricalSource exposed by the data model:

<navigation:ExamplePage xmlns:navigation="navigation/example-page" loaded="onPageLoaded"  xmlns:chart="nativescript-telerik-ui-pro/chart" xmlns="http://www.nativescript.org/tns.xsd">
    <chart:RadCartesianChart id="cartesianChart">
        <chart:RadCartesianChart.series>
            <chart:BarSeries items="{{ categoricalSource }}" categoryProperty="Country" valueProperty="Amount">

                <chart:BarSeries.horizontalAxis>
                    <chart:CategoricalAxis/>
                </chart:BarSeries.horizontalAxis>
                <chart:BarSeries.verticalAxis>
                    <chart:LinearAxis/>
                </chart:BarSeries.verticalAxis>
            </chart:BarSeries>
        </chart:RadCartesianChart.series>
    </chart:RadCartesianChart>
</navigation:ExamplePage>

The following screenshots demonstrate how your page looks like on iOS and Android:

Chart series overview Chart series overview

Stack Mode

There are scenarios in which a single Categorical chart can host multiple series. The stackMode property allows you to define how these series will interact with each other. The following options are available for the stackMode property:

  • None - series are displayed on top of each other in the order they are added in the chart
  • Stack - separate data points which reside in the same category are stacked on top of each other in the order they are added in the chart
  • Stack100 - separate data points which reside in the same category are stacked on top of each other and positioned proportionally so that the whole plot-area of the chart is filled

This is the data with which we will populate our series:

get firstSeries() {
    return [
        { Country: "Germany", Amount: 320, SecondVal: 14, ThirdVal: 24 },
        { Country: "France", Amount: 206, SecondVal: 23, ThirdVal: 25 },
        { Country: "Bulgaria", Amount: 100, SecondVal: 17, ThirdVal: 23 },
        { Country: "Spain", Amount: 25, SecondVal: 19, ThirdVal: 24 },
        { Country: "USA", Amount: 85, SecondVal: 8, ThirdVal: 21 }
    ]
}

get secondSeries() {
    return [
        { Country: "Germany", Amount: 120, SecondVal: 14, ThirdVal: 24 },
        { Country: "France", Amount: 56, SecondVal: 23, ThirdVal: 25 },
        { Country: "Bulgaria", Amount: 300, SecondVal: 17, ThirdVal: 23 },
        { Country: "Spain", Amount: 95, SecondVal: 19, ThirdVal: 24 },
        { Country: "USA", Amount: 405, SecondVal: 8, ThirdVal: 21 }
    ]
}

get thirdSeries() {
    return [
        { Country: "Germany", Amount: 96, SecondVal: 14, ThirdVal: 24 },
        { Country: "France", Amount: 139, SecondVal: 23, ThirdVal: 25 },
        { Country: "Bulgaria", Amount: 276, SecondVal: 17, ThirdVal: 23 },
        { Country: "Spain", Amount: 300, SecondVal: 19, ThirdVal: 24 },
        { Country: "USA", Amount: 100, SecondVal: 8, ThirdVal: 21 }
    ]
}

In our page definition, we set the bindingContext of the page to point to a stackedSeriesModel object:

var context = new stackedSeriesModel.ViewModel();
export function onPageLoaded(args) {
    var page = args.object;
    page.bindingContext = context;
}

The following XML snippet demonstrates combining three Area series in a single chart and defining a stack mode:

<navigation:ExamplePage xmlns:navigation="navigation/example-page" loaded="onPageLoaded" navigatedTo="onNavigatedTo" xmlns:chart="nativescript-telerik-ui-pro/chart" xmlns="http://www.nativescript.org/tns.xsd"> 
    <navigation.actionBar>
         <ActionBar title="Stacked Area">
            <ActionBar.actionItems>
             <ios>
               <ActionItem text="Options" ios.position="right" tap="{{onOptionsTapped}}" />

             </ios>
             <android>
                    <ActionItem text="Stack 100" android.position="popup" tap="onStack100ModeSelected" />
                    <ActionItem text="Stack" android.position="popup" tap="onStackModeSelected" />
                    <ActionItem text="None" android.position="popup" tap="onNoneStackModeSelected" />
             </android>
            </ActionBar.actionItems>
             </ActionBar>
            </navigation.actionBar>
    <chart:RadCartesianChart id="cartesianChart">
        <chart:RadCartesianChart.series>
            <chart:AreaSeries items="{{ firstSeries }}" stackMode="Stack" categoryProperty="Country" valueProperty="Amount">


            </chart:AreaSeries>
            <chart:AreaSeries items="{{ secondSeries }}" stackMode="Stack" categoryProperty="Country" valueProperty="Amount">


            </chart:AreaSeries>
            <chart:AreaSeries items="{{ thirdSeries }}" stackMode="Stack" categoryProperty="Country" valueProperty="Amount">


            </chart:AreaSeries>
        </chart:RadCartesianChart.series>
        <chart:RadCartesianChart.horizontalAxis>
            <chart:CategoricalAxis/>
        </chart:RadCartesianChart.horizontalAxis>
        <chart:RadCartesianChart.verticalAxis>
            <chart:LinearAxis/>
        </chart:RadCartesianChart.verticalAxis>
    </chart:RadCartesianChart>
</navigation:ExamplePage>

Here's how your chart will look like with stackMode set to Stack100:

Chart series overview Chart series overview

Pie series

Pie series are a separate type of series that are used in context with a Pie chart. There are two types of Pie series supported by Chart for NativeScript:

  • Pie - data is represented in the form of a pie where separate data-points are visualized as a slice of the pie
  • Donut - the Pie series principles apply here with the only difference that there is a 'hole' in the middle of the pie which makes it look like a donut