Create a Widget

This tutorial is the first one in the Getting Started series where you will learn how to add and configure the widgets that are supplied with the ChartJS. This tutorial details which libraries should be included into a project and how to add a widget to a page.

Add Libraries

To use ChartJS widgets, reference the following libraries on your page.

  • jQuery version 2.0.3 (but 1.10.2 for IE 8)
  • A data-binding library (optionally): Knockout version 3.0.0 or AngularJS version 1.1.1
  • Globalize
  • ChartJS (the whole library or the required modules only)

NOTE: Reference the libraries in the same order as they are listed above.

There are three possible ways of providing links to the necessary files.

Use Manually Installed Libraries

Download a zip-archive with the latest version of the ChartJS library. Unpack it and place the Lib/js folder in the folder with your application. In this instance, the links you have to add to your application will be:

HTML
<script src="js/jquery-2.0.3.min.js"></script>
<!--script src="js/knockout-3.0.0.js"></script-->
<!--script src="js/angular.min.js"></script-->
<script src="js/globalize.min.js"></script>
<script src="js/dx.chartjs.js"></script>

If you plan to use only certain widgets from the ChartJS library, reference the corresponding modules along with the required core modules instead of the whole library.

HTML
<script src="js/dx.module-core.js"></script> <!-- required -->
<script src="js/dx.module-viz-core.js"></script> <!-- required -->
<script src="js/dx.module-viz-charts.js"></script> <!-- dxChart and dxPieChart -->
<script src="js/dx.module-viz-gauges.js"></script> <!-- dxCircularGauge, dxLinearGauge and dxBarGauge -->
<script src="js/dx.module-viz-rangeselector.js"></script> <!-- dxRangeSelector -->
<script src="js/dx.module-viz-sparklines.js"></script> <!-- dxSparkline and dxBullet -->
<script src="js/dx.module-viz-vectormap.js"></script> <!-- dxVectorMap -->

Use a CDN

It is not always necessary to deliver libraries with a published site. There are time, when it is best to use a link to these libraries from a Content Delivery Network (CDN). This can improve the performance of your applications.

The DevExpress CDN hosts the ChartJS library and enables you to easily add it to your Web applications. A link to this library should be added in the following manner.

HTML
<script type="text/javascript" src="http://cdn3.devexpress.com/jslib/13.2.13/js/dx.chartjs.js"></script>

To use the jQuery, Knockout and globalize libraries in the same manner as the ChartJS library, use the Microsoft Ajax CDN and Google CDN.

HTML
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-2.0.3.min.js"></script>
<!--script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/knockout/knockout-3.0.0.js"></script-->
<!--script type="text/javascript" src="https://ajax.googleapis.com/ajax/libs/angularjs/1.1.1/angular.min.js"></script-->
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/globalize/0.1.1/globalize.min.js"></script>

To add the globalize library for all cultures, use the globalize.cultures.js file. To add a library for a specific culture, replace {culture-code} with the desired culture code in the globalize.culture.{culture-code}.js file. For instance, you can add Spanish localization using the globalize.culture.es-MX.js file.

HTML
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/globalize/0.1.1/globalize.culture.es-MX.js"></script>

Use a NuGet Package

When using Visual Studio for developing, you can easily add the ChartJS library to your application using the ChartJS NuGet package. To do this, follow the steps below.

  1. Right-click your project in the Solution Explorer window and choose Manage NuGet Packages... in the context menu.

    NuGetVS

  2. Choose Online in the right column of the appeared window.

    NuGetVS

    Make sure that you have nuget.org as your online source. Then, type ChartJS within the Search Online text box.

  3. When the search is complete, click the Install button of the found item.

    NuGetVS

After the successful install of the ChartJS NuGet package, you will find it in the list of installed packages along with the Globalize and jQuery packages upon which the ChartJS library depends.

NuGetVS

Once you have installed the ChartJS NuGet package, you will be able to update the ChartJS library to the newest version from the Updates section of the Manage NuGet Packages window.

Now, to use the ChartJS library, provide links to the library and its dependencies. Add the following code to your application.

HTML
<script src="/Scripts/jquery-2.0.3.min.js"></script>
<script src="/Scripts/globalize/globalize.js"></script>
<script src="/Scripts/dx.chartjs.js"></script>

NOTE: The Knockout and AngularJS libraries are not included in the ChartJS NuGet package.

You can find more information about the ChartJS NuGet package in the NuGet Gallery.

To learn how to install NuGet, refer to the Installing NuGet article.

Add a Widget

Once you've linked the necessary files, you can add a widget to your page. There are three possible approaches to creating a widget. Use the one that is more appropriate for your project.

jQuery Approach

Add a div element within the body of the page.

HTML
<div id="chartContainer" style="max-width:800px;height: 400px;"></div>

ChartJS supplies jQuery plugins for each widget.

  • dxChart()
  • dxPieChart()
  • dxCircularGauge()
  • dxLinearGauge()
  • dxBarGauge()
  • dxRangeSelector()
  • dxBullet()
  • dxSparkline()
  • dxVectorMap()

The following code demonstrates how to create the dxChart widget within the "chartContainer" element using the dxChart jQuery plugin.

JavaScript
$(function () {
    $("#chartContainer").dxChart();
});

To configure a widget, pass a configuration object as the constructor's parameter. The properties of this object represent the widget's configuration options. To specify the options, set the required values to the configuration object properties.

JavaScript
$(function () {
    $("#chartContainer").dxChart({
        dataSource: [
            //...
        ],
        series: {valueField: 'costs', argumentField: 'day'}
    });
});

Knockout Approach

To automatically update the UI parts of your application whenever a data model changes, the "Dependency Tracking" feature offered by Knockout is rather useful. ChartJS supplies custom Knockout bindings for each widget.

  • dxChart
  • dxPieChart
  • dxCircularGauge
  • dxLinearGauge
  • dxRangeSelector
  • dxBullet
  • dxSparkline
  • dxVectorMap

The following code demonstrates how to use the dxChart binding to create the dxChart widget.

HTML
<div id="chartContainer" style="max-width:800px;height: 400px;" data-bind="dxChart: {dataSource: dataSource, series: {valueField: 'costs', argumentField: 'day'}}"></div>

To configure a widget, specify a configuration object. The properties of this object represent the widget's configuration options. To specify the options, set the required values to the configuration object's properties. In the code above, the chart's dataSource option is set to a value that is specified by the corresponding ViewModel field.

JavaScript
$(function() {
    var viewModel = {
        dataSource: [
            //...
        ]
    };
    ko.applyBindings(viewModel);
});

You can bind an entire configuration object to the ViewModel's field if it is appropriate for your needs.

HTML
<div id="chartContainer" style="max-width:800px;height: 400px;" data-bind="dxChart: chartOptions"></div>
JavaScript
$(function() {
    var viewModel = {
        chartOptions: {
            dataSource: dataSource,
            series: {valueField: 'costs', argumentField: 'day'}
        }
    };
    ko.applyBindings(viewModel);
});

AngularJS Approach

ChartJS widgets can be used in applications built using the AngularJS version 1.1 framework. In this topic, you will learn how to create a ChartJS widget using AngularJS.

Watch Video

For operating with AngularJS, the ChartJS library includes an AngularJS module registered under the name "dx". This module contains registered directives for all ChartJS widgets. Include this module in a list of dependencies for your application module.

JavaScript
angular.module('myApp', [ 'dx' ]);

To create a ChartJS widget on a page, add a div element and set the corresponding directive. The directive name should correspond to AngularJS normalization rules: dx-widget-name. For instance, use the dx-chart directive to create the dxChart widget.

HTML
<div dx-chart=""></div>

To configure a widget, specify a configuration object within the directive's expression. The fields of this object represent widget configuration options.

HTML
<div dx-chart="{ 
    dataSource: [
        //...
    ],
    series: {valueField: 'costs', argumentField: 'day'} 
 }"></div>

You can set configuration options to the values that are specified in the scope. In the code below, the dxChart's dataSource option is set to the dataSource array that is defined within the scope of the controller.

HTML
<div ng-controller="Controller">
    <div dx-chart="{ dataSource: dataSource, series: {valueField: 'costs', argumentField: 'day'} }"></div>
</div>
JavaScript
function Controller($scope) {
    $scope.dataSource = [
        //...
    ]
}

You can also set an object from the scope as a configuration object of a widget.

HTML
<div ng-controller="Controller">
    <div dx-chart="chartOptions"></div>
</div>
JavaScript
function Controller($scope) {
    $scope.chartOptions = {
        dataSource: [
            //...
        ],
        series: {valueField: 'costs', argumentField: 'day'} 
    }
}

Use TypeScript

Optionally, you can use TypeScript when configuring or accessing ChartJS widgets. This topic provides details on creating a ChartJS widget using TypeScript.

Watch Video

Download a .ts file with TypeScript definitions from GitHub. Copy this file to your project. In your TypeScript file, add a reference to this file and the .ts files that include TypeScript definitions for the jQuery (or Knockout) and globalize libraries.

/// <reference path="TypeScript/jquery.d.ts" />
/// <reference path="TypeScript/globalize.d.ts" />
/// <reference path="TypeScript/dx.chartjs.d.ts" />

Configure ChartJS Widgets

No matter what approach you use to create a ChartJS widget - jQuery, Knockout or AngularJS - you can define configuration options using TypeScript instead of JavaScript. Here is an example.

window.onload = () => {
    var options: DevExpress.viz.charts.ChartOptions;
    options = {
        dataSource: [
            //...
        ],
        series: {valueField: 'costs', argumentField: 'day'} 
    };
    //Create a dxChart widget using the jQuery approach
    $('#chartContainer').dxChart(options);    
};

Access ChartJS Widget Instance

The variable to which you should assign a widget instance in TypeScript must be of a DevExpress.viz.Chart type.

var chartInstance: DevExpress.viz.Chart;
chartInstance = $('#chartContainer').dxChart('instance');
chartInstance.clearSelection();