Blog

How to Customize Ignite UI Doughnut Chart Control

[Infragistics] Mihail Mateev / Monday, January 26, 2015

The igDoughnutChart displays data similar to a pie chart and can display multiple sets of data around a common center. With the Ignite UI Doughnut chart you can easily display multiple rings at the same time, and are capable of binding the same or different collections. Usually, this chart is used to show categorical statistics expressed in percentages. It exposes various options, allowing you to customize its appearance and the way your data is visualized. It allows for proportionally illustrating the occurrences of a variable. The inner radius of the control is configurable, and the Doughnut Chart’s series provides a built-in support for selecting and exploding its slices.

 

This blog will cover several main settings used to configure and customize the igDoughnutChart components:

  • Configure Basic Settings
  • Configure Legend
  • Bind to JSON
  • Labels and Tooltips
  • Styling and Theming

 

Before you start:

To add igDoughnutChart to your web application, you need the required JavaScript and CSS files referenced on the HTML page.

 

<link href="css/themes/infragistics/infragistics.theme.css" rel="stylesheet" />
<link href="css/structure/infragistics.css" rel="stylesheet" />
<script src="js/modernizr.min.js"></script>
<script src="js/jquery.min.js"></script>
<script src="js/jquery-ui.min.js"></script>
<!-- Ignite UI Required Combined JavaScript Files -->
<script src="js/infragistics.core.js"></script>
<script src="js/infragistics.dv.js"></script>

If you don’t want to host source scripts and prefer to use a CDN you need to add these resources:

 

<script src="http://igniteui.com/js/modernizr.min.js"></script>
<script src="http://code.jquery.com/jquery-1.9.1.min.js"></script>
<script src="http://code.jquery.com/ui/1.10.3/jquery-ui.min.js"></script>
<script src="http://cdn-na.infragistics.com/igniteui/latest/js/infragistics.core.js"></script>
<script src="http://cdn-na.infragistics.com/igniteui/latest/js/infragistics.dv.js"></script>
<link href="http://cdn-na.infragistics.com/igniteui/latest/css/themes/infragistics/infragistics.theme.css" rel="stylesheet"></link>
<link href="http://cdn-na.infragistics.com/igniteui/latest/css/structure/infragistics.css" rel="stylesheet"></link>

 

Adding Ignite UI Doughnut Chart to HTML page:

To do this, you'll need to add a div element in the body of your HTML page, which is used to create the Doughnut Chart:

 

<div style='text-align: center; width: 100%; font:16px Arial, Helvetica, sans-serif;'>1990 Population</div>
<div style='text-align: center; width: 100%; margin: 10px 0; font:12px Arial, Helvetica, sans-serif;'>Top 5 largest countries by population (in millions)</div>

<!-- Target element for the igDoughnutChart -->
<div id='chart'></div>

 

Next you need to instantiate the igDoughnutChart control.

 

$("#chart").igDoughnutChart({
    width: "100%",
    height: "550px",
    series:
    [{
        name: "Pop1990",
        labelMemberPath: "CountryName",
        valueMemberPath: "Pop1990",
        dataSource: data,
        labelsPosition: "bestFit",
        formatLabel: function (context) {
            return context.itemLabel + " (" + context.item.Pop1990 + ")";
        }
    }]
});

 

The picture below demonstrates generated Doughnut Chart:

If you need to add the Ignite UI Doughnut Chart control to your ASP.NET MVP project with ASPX views, you'll need to follow these steps:

1. Import the Infragistics.Web.Mvc namespace

 
 

2. Add references to the combined files for all data visualization controls

<link href="<%=Url.Content("~/Scripts/css/structure/modules/infragistics.ui.chart.css")%>" rel="stylesheet"></link>
<link href="<%=Url.Content("~/Scripts/css/themes/infragistics/infragistics.theme.css")%>" rel="stylesheet"></link>
<script src="<%=Url.Content("~/Scripts/jquery.min.js")%>" type="text/javascript"></script>
<script src="<%=Url.Content("~/Scripts/jquery-ui.min.js")%>" type="text/javascript"></script>
<script src="<%=Url.Content("~/Scripts/js/infragistics.core.js")%>" type="text/javascript"></script>
<script src="<%=Url.Content("~/Scripts/js/infragistics.dv.js")%>" type="text/javascript"></script>

 

3. Instantiate the igDoughnutChart control in the ASPX view

<body>
    <%= Html.Infragistics().DoughnutChart()
                    .Width("300px")
                    .Height("300px")
                    .Series(s =>
                    {
                        s.Ring("flatSeries", Model.AsQueryable())
                            .ValueMemberPath(o => o.Index);
                        })
                     .Render()%>
</body>

 

 

Configure Basic Settings

To configure your basic settings, your options can be divided in two groups: options for the whole doughnut and options for the series. The first group contains options that control the behavior of all of the slices, while the second group allows you to choose the slices color, labels, style and etc.

Doughnut options:

There are two basic options that corresponds to the slices actions. The allowSliceExplosion option makes the slices pop out of their places when a user clicks on them, and the allowSliceSelection option makes the slices selectable – that means when a user clicks on a particular slice it can change its style or trigger a client event. Both of those options are of Boolean type. You also need to initialize the sliceClick event if you want the mentioned properties to work.

 

sliceClick: function (e, ui) {
    ui.slice.isSelected = !ui.slice.isSelected;
    ui.slice.isExploded = !ui.slice.isExploded;
}

 

$("#chart").igDoughnutChart({
    width: "70%",
    height: "550px",
	allowSliceExplosion: true,
    allowSliceSelection: true,
    series:
    [{
        name: "Pop1990",
        labelMemberPath: "CountryName",
        valueMemberPath: "Pop1990",
        dataSource: data,
        labelsPosition: "bestFit",
        formatLabel: function (context) {
            return context.itemLabel + " (" + context.item.Pop1990 + ")";
        }
    }]
});

Since this is a doughnut chart. it has a “blank circle” for a center, but actually you can control the radius of that circle with the innerExtent option and make it as big or as small as you want - or get rid of it.

innerExtent: 20

 

Series options:

There are plenty of options by which you can manipulate the series. We are going to look at some of them, but you can find the whole list in the API documentation.  You can have as many slices for you chart as you need, but remember that it's useful to make each slice a different color to be able to distinguish their sizes easily. For that purpose you can use the brushes property. This defines the palette from which automatically assigned slice brushes are selected. The value provided should be an array of CSS color strings.

brushes: ["#B284BE", "#5D8AA8", "#C9FFE5", "#7CB9E8", "#F19CBB", "#FAEBD7"]

 

Configure Legend

You need to supply a dom element to use for the legend. This element defines the position of the legend.

// You need to supply a dom element to use for the legend (preferably a div element)
// Initialize
$("#chart").igDoughnutChart({
   series: 
      [{
          legend: $("selectorForLegendElement"),
          valueMemberPath: "Pop1990",
          name: "Pop1990",
          dataSource: data
      }]
});
 
// Get
var series = $("#chart").igDoughnutChart("option", "series");
series[0].legend;
 
// Set
$("#chart").igDoughnutChart("option", "series", [{ name: "Pop1990", legend: $("selectorForLegendElement") }]);

Bind to JSON

JSON, or JavaScript Object Notation, is an open standard format that uses human-readable text to transmit data objects consisting of attribute–value pairs. It is used primarily to transmit data between a server and web applications. One of the main cases is how to bind series to JSON arrays.

Let’s have a JSON array like this one shown below:

var data = [
	{ "CountryName": "China", "Pop1990": 1141 },
	{ "CountryName": "India", "Pop1990": 849 },
	{ "CountryName": "United States", "Pop1990": 250 },
	{ "CountryName": "Indonesia", "Pop1990": 178 },
	{ "CountryName": "Brazil", "Pop1990": 150 }
];

The dataSource option of the series is used to provide bindings:

 

$("#chart").igDoughnutChart({
	width: "100%",
	height: "550px",
	series:
	[{
		name: "Pop1990",
		labelMemberPath: "CountryName",
		valueMemberPath: "Pop1990",
		dataSource: data,
		labelsPosition: "bestFit",
		formatLabel: function (context) {
			return context.itemLabel + " (" + context.item.Pop1990 + ")";
		}
	}]
});

Labels and Tooltips

Labels and Tooltips in the igDoughnutChart series can be maintained via four properties:

  1. series.showTooltip
  2. series.tooltipTemplate
  3. series.labelMemberPath
  4. series.labelsPosition

 

The snippet below shows Ignite UI Donut Chart with two series where these properties are set from code:

 

$("#chart").igDoughnutChart({
	width: "100%",
	height: "550px",
	innerExtent: 20,
	series:
		[
			{
				name: "Budget",
				labelMemberPath: "Label",
				valueMemberPath: "Budget",
				dataSource: data,
				labelsPosition: "center",
				showTooltip: true,
				tooltipTemplate: "budgetTooltipTemplate"
			},
			{
				name: "DepartmentSize",
				labelMemberPath: "Label",
				valueMemberPath: "DepartmentSize",
				dataSource: data,
				labelsPosition: "outsideEnd",
				showTooltip: true,
				tooltipTemplate: "<div class='ui-chart-tooltip'><div class='bold'>${item.Label}</div><div>Department Size: <label class='bold'>${item.DepartmentSize}</label></div></div>"
			}
		]
});

Styling and Theming:

Your styling and theming customization gets or sets the style used when a slice is selected: selectedStyle option

 

// Initialize
$("#chart").igDoughnutChart({
    selectedStyle : { fill: "red", stroke: "blue", strokeThickness: 3, opacity: 1 }
});
 
// Get
var selectedStyle = $('#chart').igDoughnutChart('option', 'selectedStyle');
 
// Set
$('#chart').igDoughnutChart(
'option', 'selectedStyle', { 
fill: 'red', stroke: 'blue', strokeThickness: 3, opacity: 1 
});

 

The Ignite UI Doughnut Chart is not affected by Theming - it has no styling elements that could be set via themes.

An igDoughnutChart Example – all settings together

Now that we've gone through our options, let’s put everything into one example:

The sample below includes most of basic settings, selection and selection styling, series binding etc.

 

$(function () {

        var data = [
                        { "savings": 210, "Budget": 600, "Label": "George" },
                        { "savings": 100, "Budget": 400, "Label": "Sam" },
                        { "savings": 250, "Budget": 550, "Label": "John" },
                        { "savings": 29, "Budget": 300, "Label": "Mike" },
                        { "savings": 130, "Budget": 650, "Label": "David" },
                        { "savings": 54, "Budget": 200, "Label": "Sally" }
        ];

        var array = new Array();
        $("#chart").igDoughnutChart({
            width: "450px",
            height: "450px",
            innerExtent: 10,
            allowSliceExplosion: true,
            allowSliceSelection: true,
            sliceClick: function (e, ui) {
                ui.slice.isSelected = !ui.slice.isSelected;
                ui.slice.isExploded = !ui.slice.isExploded;
                array.push(ui.slice);
                $("#selectedItem").empty();
                for (var i = 0; i < array.length; i++) {
                    if (array[i].isSelected) {
                        $("#selectedItem").append("<p id=" + array[i].item.Label + ">" + array[i].item.Label + " recieves " + array[i].item.Budget + "$ and manage to saves " + array[i].item.savings + "$.</p>");
                    }
                    if (!(array[i].isSelected)){
                        $("#" + array[i].item.Label).remove();
                        
                    }
                }
            },
            series:
                [
                    {
                        name: "Budget",
                        labelMemberPath: "Label",
                        valueMemberPath: "Budget",
                        dataSource: data,
                        labelsPosition: "bestFit",
                        brushes: ["#B284BE", "#5D8AA8", "#C9FFE5", "#7CB9E8", "#F19CBB", "#FAEBD7"],
                        legend: { element: "legend1" },
                        selectedStyle: { fill: "lightpink", stroke: "black" },
                        showTooltip: true,
                        tooltipTemplate: "budgetTooltipTemplate"
                    },
                    {
                        name: "savings",
                        labelMemberPath: "Label",
                        valueMemberPath: "savings",
                        dataSource: data,
                        labelsPosition: "bestFit",
                        brushes: ["#7FFFD4", "#FF91AF", "#BCD4E6", "#FAE7B5", "#A2A2D0", "#FBEC5D"],
                        selectedStyle: { fill: "#FF6A6F", stroke: "black" },
                        showTooltip: true,
                        tooltipTemplate: "savings Template",
                        legend: { element: "legend2" }
                    }
                ]

        });

    });

 

 

The Infragistics jQuery Doughnut Chart supports a lot of other features which can help you customize it according to your needs. You can find a detailed information about the control and its features and how to configure its separate parts in the API documentation as we as the online help documentation.

To play around with the Doughnut Chart on your own, be sure to get Infragistics Ultimate and see the chart in action in our latest sample application by clicking the banner below!