How to Customize Ignite UI Bullet Graph Control

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

The Ignite UI Bullet Graph (igBulletGraph) control is an Ignite UI component which allows for visualizing data in the form of a bullet graph. Linear by design, it provides a simple and concise view of a primary measure or measures compared against a scale and, optionally, some other measure. This control is similar to the Linear Gauge but apart from the current value it also shows a target value which can serve as a point to reach or a measurement . It is usually used to compare two values one represented by a horizontal bar and another represented by a vertical line. You can display the chart separately or you can insert it in a Grid and thus create a graphical table for even better UX.

This blog will cover several main settings, used to configure and customize igBulletGraph components:

Configure Basic Settings
Scale Labeling Settings
Tick Marks Settings
How to change igBulletGraph Orientation
Configuring the jQuery Bullet Graph Background

Before to start:

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

<!DOCTYPE html>
<html>
<head>
    <!-- Ignite UI Required Combined CSS Files -->
    <link href="../../igniteui/css/themes/infragistics/infragistics.theme.css" rel="stylesheet" />
    <link href="../../igniteui/css/structure/infragistics.css" rel="stylesheet"/>
    <script type="text/javascript" src="../../js/jquery.min.js"></script>
    <script type="text/javascript" src="../../js/jquery-ui.js"></script>
    <!-- Bullet Graph Required JavaScript Files -->
    <script src="../../igniteui/js/modules/infragistics.util.js" type="text/javascript"></script>
    <script src="../../igniteui/js/modules/infragistics.dv.simple.core.js" type="text/javascript"></script>
    <script src="../../igniteui/js/modules/infragistics.gauge_bulletgraph.js" type="text/javascript"></script>
    <script src="../../igniteui/js/modules/infragistics.ui.bulletgraph.js" type="text/javascript"></script>
</head>
<body>
<!-- your implementation here -->
</body>
</html>

To add a Bullet Graph to your page you need to create an element within the HTML body on which to instantiate the igBulletGraph control.

<body>
     <!-- Target element for the igBulletGraph -->
       <div id="bulletGraph"></div>
</body>

Next you need to instantiate the igBulletGraph control.

<script type="text/jscript">
     $(function () {                        
               $("#bulletGraph").igBulletGraph({
         });
         });
</script>

Configure Basic Settings

When instantiating the igBulletGraph, configure the width and height options.
In HTML:

$("#bulletGraph").igBulletGraph({
     width: "320px",
     height: "80px"
 });

Configure the scale: You need to set its minimumValue and maximumValue properties. For example, the scale will start at 5 and end at 55.

$("#bulletGraph").igBulletGraph({
     width: "300px",
     height: "70px",
     minimumValue: "5",
     maximumValue: "55"
 });

Add a performance bar: The primary measure of the igBulletGraph is visualized by its performance bar. Its value is managed by the value property setting.

$("#bulletGraph").igBulletGraph({
     …
     value:"35"
 });

Configure the comparative marker: To position the comparative measure marker on the scale is managed by the value of the targetValue property.

$("#bulletGraph").igBulletGraph({
     …
     targetValue:"43"
 });

Add comparative ranges: Comparative ranges are managed by ranges property within which several individual ranges can be defined, each of which having its own starting and ending values (startValue and endValue) and color (brush).

$("#bulletGraph").igBulletGraph({
     …
     ranges: [{
         name: 'range1',
         startValue: 0,
         endValue: 15,
         brush: '#DCDCDC'
     },
     {
         name: 'range2',
         startValue: 15,
         endValue: 30,
         brush: '#A9A9A9'
     },
     {
         name: 'range3',
         startValue: 30,
         endValue: 55,
         brush: '#808080'
     }
     ]
 });

The final result looks like the bullet graph at the picture below:

Scale Labeling Settings

You can control the labeling settings as

formatLabel:

formatLabel: function (evt, ui) {
	ui.label = "$" + ui.label;
	if (ui.value != 90000000) {
		var re = /000$/;
		ui.label = ui.label.replace(re, " K");
	}
}

and alignLabel

alignLabel: function (evt, ui) {
	// center the just the number part according to its tick, instead of centering the whole label
	if (ui.value == 90000000) {
		ui.offsetX += 20;
	}
}

The full code is available below:

$bulletGraph.igBulletGraph({
                    height: "80px",
                    width: "100%",
                    interval: 15000000,
                    fontBrush: "#164F6D",
                    formatLabel: function (evt, ui) {
                        ui.label = "$" + ui.label;
                        if (ui.value != 90000000) {
                            var re = /000$/;
                            ui.label = ui.label.replace(re, " K");
                        }
                    },
                    alignLabel: function (evt, ui) {
                        // center the just the number part according to its tick, instead of centering the whole label
                        if (ui.value == 90000000) {
                            ui.offsetX += 20;
                        }
                    },
                    ranges: [
                        {
                            name: 'range1',
                            startValue: 0,
                            endValue: 45000000,
                            brush: '#164F6D'
                        },
                        {
                            name: 'range2',
                            startValue: 45000000,
                            endValue: 60000000,
                            brush: '#20789F'
                        },
                        {
                            name: 'range3',
                            startValue: 60000000,
                            endValue: 100000000,
                            brush: '#36A5D5'
                        }
                    ],
                    maximumValue: 100000000,
                    targetValue: 75000000,
                    value: 73000000,
                    transitionDuration: 500,
                    valueBrush: "white",
                    valueOutline: "white",
                    targetValueBrush: "white",
                    targetValueOutline: "white"
 });

The picture below demonstrates Ignite UI Bullet Graphs with different formatting of the labels:

Tick Marks Settings

Tick marks has many settings that allow you to configure it:

tickStartExtent: Gets or sets the position at which to start rendering the major tickmarks as a value from 0 to 1, measured from the front/bottom of the gauge
tickEndExtent: Gets or sets the position at which to stop rendering the major tickmarks as a value from 0 to 1
ticksPostInitial: A value to start adding tickmarks, added to the scale's MinimumValue
ticksPreTerminal: A value to stop adding tickmarks, subtracted from the scale's MaximumValue.
tickStrokeThickness: Gets or sets the stroke thickness to use when rendering ticks.
tickBrush: Gets or sets the brush to use for the major tickmarks.
minorTickCount: Gets or sets the number of minor tickmarks to place between major tickmarks.
minorTickStartExtent: Gets or sets the position at which to start rendering the minor tickmarks as a value from 0 to 1, measured from the front/bottom of the gauge.
minorTickEndExtent: Gets or sets the position at which to stop rendering the minor tickmarks as a value from 0 to 1, measured from the front/bottom of the gauge.
minorTickStrokeThickness: Gets or sets the stroke thickness to use when rendering minor ticks
minorTickBrush: Gets or sets the brush to use for the minor tickmarks.

The whole code is available below:

        $(function () {
            $("#bulletgraph1").igBulletGraph({
                height: '80px',
                width: '100%',
                // The interval to use for the ticks. Default value is calculated, rather than predefined, to show 11 ticks based on the minimum and maximum values (in this case value would equal to 75)
                //interval: 75,
                // Gets or sets the position at which to start rendering the major tickmarks as a value from 0 to 1, measured from the front/bottom of the gauge.
                // Values further from zero than 1 can be used to make this extend further than the normal size of the gauge.
                tickStartExtent: 0.02,
                // Gets or sets the position at which to stop rendering the major tickmarks as a value from 0 to 1, measured from the front/bottom of the gauge.
                // Values further from zero than 1 can be used to make this extend further than the normal size of the gauge.
                tickEndExtent: 0.2,
                // A value to start adding tickmarks, added to the scale's MinimumValue.
                ticksPostInitial: 0,
                // A value to stop adding tickmarks, subtracted from the scale's MaximumValue.
                ticksPreTerminal: 0,
                // Gets or sets the stroke thickness to use when rendering ticks.
                tickStrokeThickness: 2,
                // Gets or sets the brush to use for the major tickmarks.
                tickBrush: 'black',
                // Gets or sets the number of minor tickmarks to place between major tickmarks.
                minorTickCount: 3,
                // Gets or sets the position at which to start rendering the minor tickmarks as a value from 0 to 1, measured from the front/bottom of the gauge.
                // Values further from zero than 1 can be used to make this extend further than the normal size of the gauge.
                minorTickStartExtent: 0.06,
                // Gets or sets the position at which to stop rendering the minor tickmarks as a value from 0 to 1, measured from the front/bottom of the gauge.
                // Values further from zero than 1 can be used to make this extend further than the normal size of the gauge.
                minorTickEndExtent: 0.2,
                // Gets or sets the stroke thickness to use when rendering minor ticks.
                minorTickStrokeThickness: 1,
                // Gets or sets the brush to use for the minor tickmarks.
                minorTickBrush: '#EBEBEB',
                ranges: [
                    {
                        name: 'range1',
                        startValue: 0,
                        endValue: 450 
                    },
                    {
                        name: 'range2',
                        startValue: 450,
                        endValue: 600,
                    },
                    {
                        name: 'range3',
                        startValue: 600,
                        endValue: 750
                    }
                ],
                maximumValue: 750,
                targetValue: 550, 
                value: 555 
            });
 });

The picture below shows different settings of igBulletGraph tick marks:

How to change igBulletGraph Orientation

Property “orientation” can be used to change orientation using values “horizontal” or “vertical”.

$(function () {

            $("#bulletgraph").igBulletGraph({
                height: "300px",
                width: "60px",
                orientation: "vertical", 
                value: 85,
                targetValue: 77,
                ranges: [
                    {
                        name: 'bad',
                        startValue: 0,
                        endValue: 33
                    },
                    {
                        name: 'acceptable',
                        startValue: 33,
                        endValue: 70
                    },
                    {
                        name: 'good',
                        startValue: 70,
                        endValue: 100
                    }],
                transitionDuration: 200, 
            });
});

How to configure the Ignite UI Bullet Graph Background

The background of the igBulletGraph control is configurable in terms of spread and position and look-and-feel (fill and border). The spread and position are configurable in the dimension across the scale (through the backingInnerExtent and backingOuterExtent properties); along the scale, the background always spreads from one edge of the control to the other. The fill color and the border are managed by a set of properties available in the style template.

The following picture demonstrates a background color of a variety of orange and a cyan border with a thickness of 3 pixels. The background extent is made smaller by providing values for its backingInnerExtent and backingOuterExtent properties.

The screenshot below demonstrates how the igBulletGraph background:

$(function () {             
    $("#bulletGraph").igBulletGraph({
        width: "300px",
        height: "100px",
        backingBrush:'#FFDAB9',
        backingOutline: '#00FFFF',
        backingStrokeThickness: "3",
        backingInnerExtent:"0.2",
        backingOuterExtent:"0.7"
});

The bullet graph 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.

The samples above shows how you can configuring and styling different igBulletGraph elements. This post is also a brief overview of the main use cases.