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.

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

There are three possible ways to provide 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-1.9.1.min.js"></script>
<script src="js/knockout-2.2.1.js"></script>
<script src="js/globalize.min.js"></script>
<script src="js/dx.chartjs.js"></script>

Use a CDN

It is not always necessary to deliver libraries with a published site. In some situations, it is more appropriate 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.1.12/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 or Google CDN.

HTML
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/jQuery/jquery-1.9.1.min.js"></script>
<script type="text/javascript" src="http://ajax.aspnetcdn.com/ajax/knockout/knockout-2.2.1.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-1.9.1.min.js"></script>
<script src="/Scripts/globalize/globalize.js"></script>
<script src="/Scripts/dx.chartjs.js"></script>

NOTE: The Knockout library is 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 two possible approaches to creating a widget. Use the one that is more approriate 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()
  • dxRangeSelector()

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's properties.

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

NOTE: It is necessary to specify the height of a widget. This means that all of the widget's containers must have a certain height in pixels. If you set a height for the widget container's parent container, the widget's container can have a height in percent. As an alternative to the container's height, you can use the size property of the widget's configuration object to set widget height.

Knockout Approach

To automatically update 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

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);
});

NOTE: It is necessary to specify the height of a widget. This means that all of the widget's containers must have a certain height in pixels. If you set a height for the widget container's parent container, the widget's container can have a height as a percentage. As an alternative to the container's height, you can use the size property of the widget's configuration object to set widget height.