Docs

You are viewing documentation for an older Vaadin version. View latest documentation

Docs

Getting started with Vaadin Charts

Introduction

This tutorial walks you, step-by-step, through what you need to do to add Vaadin Charts to your web page.

You will learn how to:

  • Add Vaadin Charts to a web page

  • Create a simple line chart

  • Create a combined chart with dual Y-axes

  • Configure settings to change the look of the chart

  • Bind the chart to a REST service

The final result of this tutorial can be explored at GitHub.

Let us get to it.

Project Setup

The easiest way to get started is to use Bower. First, create a folder and run bower install command within it. It downloads Vaadin Charts and all the dependencies that it needs.

$ mkdir tutorial
$ cd tutorial
$ bower install --save vaadin-charts

Next create an index.html file with following content.

<!DOCTYPE html>
<html>
  <head>
    <script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
  </head>
  <body>
  </body>
</html>

The head element loads the web components. Our web page is now ready for adding Vaadin Charts to it.

Creating Your First Chart

Add a chart element to the <body> element. In this example, we are going to use <vaadin-line-chart> chart.

<vaadin-line-chart></vaadin-line-chart>

You need to import the vaadin-line-chart in the <head> element:

<link rel="import" href="bower_components/vaadin-charts/vaadin-line-chart.html">

So your index.html file should look as follows:

<!DOCTYPE html>
<html>
  <head>
    <script src="bower_components/webcomponentsjs/webcomponents-lite.min.js"></script>
    <link rel="import" href="bower_components/vaadin-charts/vaadin-line-chart.html">
  </head>
  <body>
    <vaadin-line-chart></vaadin-line-chart>
  </body>
</html>

You can now serve the index.html and check it out in the browser. One of the easiest ways to do this is to use a tool called serve (see npmjs.com for installation instructions).

$ serve
serving <Path to folder>/tutorial on port 3000

Open localhost:3000 with a browser. If you do not have a Vaadin Charts license, you will see a pop-up with a link where you can get one. Enter the license key to the pop-up. After that, you should see an empty chart with title Chart title.

Next, modify the <vaadin-line-chart> element to have a <chart-title> child element with the content Hello Charts!.

<vaadin-line-chart>
  <chart-title>Hello Charts!</chart-title>
</vaadin-line-chart>

Reload the page and you should see the new title in the chart.

Adding Some Data

Next, we are going to add data to our line chart. We have data about the average shoe size per age for girls and boys. First, let us add the data for girls. This is done by adding a <data-series> element inside the <vaadin-line-chart>.

<data-series name="Girls">
  <data>
    [17, 0.3], [18, 0.7], [19, 0.8], [20, 1.0], [21, 1.3], [22, 1.5],
    [23, 2.0], [24, 2.5], [25, 3.0], [26, 3.5], [27, 4.0], [28, 4.5],
    [29, 5.0], [30, 5.5], [31, 6.5], [32, 7.0], [33, 8.0], [34, 9.0],
    [35, 10.0], [36, 11.0]
  </data>
</data-series>

Refresh the page and you should see the data in the chart. That is awesome, but you may notice that the Y axis has a label named "values". That is not so awesome. So, let us specify our own titles there and add also the unit information. You can do it by adding the following inside the <vaadin-line-chart> element:

<x-axis>
  <chart-title>Shoe size (EU)</chart-title>
</x-axis>
<y-axis>
  <chart-title>Age (years)</chart-title>
</y-axis>

After refreshing the page, you should see a nice chart about girls average shoe size with the nice titles in the axes.

Adding Another Data Set to the Same Chart

In the previous section, we added only girls' data to the chart. Now is time to add boys there. You can do it by adding another <data-series> element inside the <vaadin-line-chart> element. We again specify a name attribute, which value will be shown in the charts legend.

<data-series name="Boys">
  <data>
    [17, 0.3], [18, 0.6], [19, 0.8], [20, 0.9], [21, 1.1], [22, 1.3],
    [23, 1.7], [24, 2.0], [25, 2.5], [26, 3.0], [27, 3.5], [28, 4.0],
    [29, 4.5], [30, 5.0], [31, 5.5], [32, 6.5], [33, 7.5], [34, 8.0],
    [35, 9.0], [36, 10.0], [37, 11.0]
  </data>
</data-series>

Refresh the page and you see two lines in the chart. They have different colors and you can see from the legend which is which. Try to click the legend items - this toggles the visibility of the data series.

Finally, change the title of the chart to something describing it, such as "Shoe size per age for boys and girls".

Configuring the Colors

Our chart looks OK now, but it would be more intuitive to read if the data for girls was rendered using a color normally associated with girls, would it not? Let us color the girl data as pink and the boy data as light blue. The colors of the lines can be changed by adding a <color> element to the <data-series>.

<data-series name="Girls">
  <color>#FF69B4</color>
  <data>
    [17, 0.3], ... , [36, 11.0]
  </data>
</data-series>
<data-series name="Boys">
  <color>#0000FF</color>
  <data>
    [17, 0.3], ..., [37, 11.0]
  </data>
</data-series>

Great! Refresh the page and you see the finished chart.

Creating a Combination Chart

Let us do something more complex next. We have historical weather data for Turku, Finland, for most of the year 2013. We will plot the temperature as a line chart and add columns for the humidity to the same chart to create a combination chart. On top of that, we will create our own web component, which will fetch the data for the chart from a REST service.

Preparations

Download the data files for the temperature and humidity. Create a folder named data in the same folder where you ran the serve command and put the downloaded files there. The data files in the folder are now served together with the index.html. Those files will mimic our REST service to fetch the weather data.

Next, we create a new web component named weather-chart that wraps the Charts component and makes REST calls to fetch the data. First, let us do it so that it only wraps the vaadin-line-chart component.

You can make it as follows:

<weather-chart></weather-chart>
<dom-module id="weather-chart">
  <template>
    <vaadin-line-chart>
      <chart-title>Turku, Finland 2013</chart-title>
      <x-axis name="Temperature" type="datetime">
        <chart-title>Date</chart-title>
      </x-axis>
      <y-axis>
        <chart-title>Temperature (°C)</chart-title>
      </y-axis>
      <data-series name="Temperature">
      </data-series>
    </vaadin-line-chart>
  </template>
  <script>
    Polymer({
      is: 'weather-chart'
    });
  </script>
</dom-module>

Next, we want to call the REST service to fetch the data and bind that to the chart. We use the iron-ajax component to make the request. Add the following inside the <template> element next to the <vaadin-line-chart>.

<iron-ajax id="temperatureFetcher"
               url="data/temperature"
               handle-as="json"
               last-response="{{temperatureData}}"
               debounce-duration="300"></iron-ajax>

The request service will write the response to the temperatureData variable, but we have not defined that yet. Let us create that as a property of the web component. Also, let us make the call to the REST service when the web component is attached to the page. These can be done by modifying the Polymer object in a <script> element.

<script>
  Polymer({
    is: 'weather-chart',
    properties: {
      temperatureData: Object
    },
    attached: function() {
      this.async(function() {
        this.$.temperatureFetcher.generateRequest();
      }, 2);
    }
  });
</script>

Now we fetch the data, but it is not yet bound to the chart. To do that, we add a data attribute to the <data-series> element.

<data-series name="Temperature" data="[[temperatureData]]">
</data-series>

Gongratulations! After page refresh, you should see the chart with the temperature data fetched from the REST service.

Adding Columns and a Second Y-axis

Let us fetch also the humidity data in our weather-chart. That can be done the similar way as we did for temperature data. First, let us create another iron-ajax component.

<iron-ajax id="humidityFetcher"
            url="data/humidity"
            handle-as="json"
            last-response="{{humidityData}}"
            debounce-duration="300"></iron-ajax>

Then, make sure that the request will be made.

attached: function() {
  this.async(function() {
    this.$.temperatureFetcher.generateRequest();
    this.$.humidityFetcher.generateRequest();
  }, 2);
}

Finally, create a <data-series> element for humidity. It should use columns instead of line.

You should have two <data-series> elements:

<data-series name="Temperature" data="[[temperatureData]]">
</data-series>
<data-series name="Humidity" type="column" data="[[humidityData]]">
</data-series>

Refresh the page and you should see a line for temperature and column bars for humidity. The chart does not look so nice yet, though. The humidity columns completely overlaps with the temperature line.

To fix the situation, we could do two things:

  1. Change the order of the data series to make the temperature line render on top of the columns.

  2. Add a second Y-axis for the humidity, as it is in percent, while the temperature is in Celsius.

The first part is simple. Just switch the order of the <data-series> elements.

To create another Y-axis for humidity, we need to create a new <y-axis> element, configure the title, the minimum value, and move it to the opposite side of the chart. Then, bind the <y-axis> to the humidity <data-series> using the id attribute.

<y-axis id="humidity">
  <chart-title>Humidity (%)</chart-title>
  <min>0</min>
  <opposite>true</opposite>
</y-axis>
...
<data-series name="Humidity" type="column" data="[[humidityData]]" y-axis = "humidity">
</data-series>

The final chart element should look as follows:

<vaadin-line-chart>
  <chart-title>Turku, Finland 2013</chart-title>
  <x-axis name="Temperature" type="datetime">
    <chart-title>Date</chart-title>
  </x-axis>
  <y-axis>
    <chart-title>Temperature (°C)</chart-title>
  </y-axis>
  <y-axis id="humidity">
    <chart-title>Humidity (%)</chart-title>
    <min>0</min>
    <opposite>true</opposite>
  </y-axis>
  <data-series name="Humidity" type="column" data="[[humidityData]]" y-axis = "humidity">
  </data-series>
  <data-series name="Temperature" data="[[temperatureData]]">
  </data-series>
</vaadin-line-chart>

Refresh the page and enjoy a better looking chart.

Summary

Congratulations! You now know the basics of how to get Vaadin Charts in your web page. For further examples, please see the on-line demo at demo.vaadin.com/vaadin-charts.

The API documentation can be explored at demo.vaadin.com/vaadin-charts-api.