jQuery Bullet Graph Introduction

Marina / Wednesday, February 12, 2014

bullet graph header imageIn my previous blogs I’ve already mentioned that Infragistics’ Ignite UI package contains a lot of controls for Data Visualization. The one we are going to talk about in this blog is the bullet graph. 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.

 

Features and Usage

The configuration of the bullet graph is easy. After adding the required Infragistics’ references as well as JavaScript and CSS files you have to create a HTML div tag to host your graph. The basic configuration of the igBulletGraph requires proving a width and a height values. If you haven’t added additional options to the configuration the control will display a scale ranging from 0 to 100 with major ticks and labels positioned  at an interval of 10. The bullet graph supports a lot of 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 configure a custom scale you should set the minimumValue and maximumValue properties. Then you can add the performance bar which visualize the primary measure of the igBulletGraph. In order to do so set the value property. The comparative marker corresponds to the targetValue property. Those  are the four values that you should configure to have a fully functional bullet graph.

When it comes to styling the control you can customize almost every part of it starting from the labels and the tick marks and ending with the performance bar and target value. We are going to take a closer look at the ranges, cause they are a tool that can help you strengthen the feeling of comparison of values. Those comparative ranges are managed by the ranges property within which several individual ranges can be defined. Each range have its own starting and ending values as well as a brush. All of the brushes of the control support gradients. But if you want only the scale to be colored using the gradients you should use the ranges brush, if you use the backingBrush property you will color the whole control. Pay attention that if you don’t set specifically values for the brush and outline properties , the values are retrieved from the values of igBulletGraph’s rangeBrushes and rangeOutlines objects. They are defined in the default theme. You can also use CSS to style the different elements. For the ranges you can use the background-image property to set a gradient color. Another thing to watch about is : if you use the “ui-bulletgraph-range-palette-n” class you should set not only the background color but the border as well.

Each range can be configured individually by specifying its starting and ending value, the border thickness and color . The width and the position of the ranges are managed by the inner and outer start and end extent. You can add a tooltips to the ranges. By default the tooltip template of the ranges shows the start and the end values separated by hyphen.

MVC:

  1. @(Html.Infragistics().BulletGraph()
  2.     .Width("100%")
  3.     .Height("80px")  
  4.     .Ranges(range =>
  5.     {
  6.         range.Range("bad").StartValue(0).EndValue(25).Brush("#E6E6E6");
  7.         range.Range("acceptable").StartValue(25).EndValue(75).Brush("#B2B2B2");
  8.         range.Range("good").StartValue(75).EndValue(100).Brush("#808080");
  9.     })
  10.     .Value(60)
  11.     .TargetValue(40)
  12.     .ValueBrush("#000")
  13.     .TargetValueBrush("#CC0000")
  14.     .FontBrush("#660000")
  15.     .TickBrush("#660000")
  16.     .TargetValueOutline("#800000")
  17.     .MinorTickCount(0)
  18.     .ClientEvents(new Dictionary<string, string>() { { "formatLabel", "function(evt, ui) { ui.label += '%' }" } })
  19.     .TransitionDuration(500)
  20.     .HtmlAttributes(new Dictionary<string, object> { { "style", "margin-bottom:40px" } })
  21.     .Render())

igBulletGraph

jQuery:

  1. $("#bulletgraph").igBulletGraph({
  2.     width: '70px',
  3.     height: '400px',
  4.     minimumValue: -10,
  5.     maximumValue: 40,
  6.     targetValue: 26,
  7.     interval: 5,
  8.     value: 20,
  9.     orientation: "vertical",
  10.     labelInterval: 5,
  11.     minorTickCount: 0,
  12.     valueBrush: "#fff",
  13.     targetValueBrush: "#000",
  14.     targetValueOutline: "#000",
  15.     transitionDuration:1000,
  16.     ranges: [{
  17.         name: "temp",
  18.         startValue: -10,
  19.         endValue: 40,
  20.         brush: {
  21.             type: "linearGradient",
  22.             colorStops: [{
  23.                 color: "#33CCFF",
  24.                 offset: 1
  25.             },
  26.             {
  27.                 color: "#FFFF00",
  28.                 offset: 0.5
  29.             },
  30.             {
  31.                 color: "#FF3300",
  32.                 offset: 0
  33.             }]
  34.         }
  35.     }],
  36.     formatLabel: function (evt, ui) {
  37.         ui.label = ui.label + "C";
  38.     }
  39. });

igBulletGraph with gradient brush for the ranges

Animation Transitions

One of the main features of the bullet graph is the animated transitions. This control provides a build-in support for animations, which can be triggered by the transitionDuration property. By default this property is disabled, but you can enable it by assigning it a positive milliseconds value.   The milliseconds value determines the timeframe for sliding the control into view by smoothly visualizing all its visual elements through a slide effect. The animations appears when the control is loading as well as when the value of any of its property is changed.

In the sample below you can see how we change the value for the graph at every second and based on that value we change the background color of the control, so that it will correspond to it.

  1. transitionDuration: 1000

igBulletGraph animation

Check out the animated transitions sample to see transitions between different sets of settings in the igBulletGraph control.

For one of the samples, that you can find at the bottom of the blog we used the animation duration to show the wind speed change in mph for the different countries. You can see a live demo on jsFiddle.

igBulletGraph animation - wind speed

Graphical Table

As I said earlier the bullet graph comes in handy when we want to display comparison between two values. By building a grid and combining it with such graph you will provide to your end-users an easy to understand and use comprehensive information.  You can check out the grid integration sample to see how to use the igBulletGraph control in a grid.

To implement  such correlation between those controls, you should add a custom row template for the grid with a special div tag that will host the bullet charts.

  1. rowTemplate: "${id}${month}${sold}${produced}
    "

The next step is to add a rowsRendered event and configure the bullet graphs in it. The minimum and maximum values as well as the target value and the value itself we will take from the data that we are using for the grid.

  1. rowsRendered: function (evt, ui) {
  2.     $(".bulletgraph3").each(function (i) {
  3.         var item = data[i];
  4.         $(this).igBulletGraph({
  5.             height: "60px",
  6.             width: "450px",
  7.             backingBrush: 'transparent',
  8.             backingOutline: 'transparent',
  9.             minimumValue: item.min,
  10.             maximumValue: item.max,
  11.             targetValue: item.produced,
  12.             value: item.sold,
  13.             interval: 100,
  14.             minorTickCount: 1,
  15.             ranges: $.map(item.ranges, function (el, index) {
  16.                 return {
  17.                     name: item.month + index,
  18.                     startValue: el.start,
  19.                     endValue: el.end
  20.                 };
  21.             }),
  22.             transitionDuration: 1200,
  23.             scaleEndExtent: 0.9,
  24.            
  25.         });
  26.     });
  27. }

 

igBulletGraph in Grid

Summary

The bullet graph control is a handy widget when it comes to comparison of two values. With its numerous features it is easy to customize and  adapt to your personal needs. It can be used separately or you can combine it with a grid and thus create a stunning app providing the best possible  user experience.

 

 

See a live demo in jsFiddle or download the ASP.NET MVC sample.

download a free trial

 

You can follow us on Twitter @Infragistics and stay in touch on Facebook, Google+ and LinkedIn!