Displaying data as a bullet chart

Problem:

You want to display data as a bullet chart.

Solution:

Example Klip

Download the sample Klip for examples discussed below.

Important Notes

• Bullet charts are supported in Klipfolio Dashboard version 5.4 and later.
• Depending on the version of Klipfolio Dashboard you are running, the data source from which the chart is generated can be in one of the 2 formats. See the Expected data format article for details.

Overview

• Use type: graph and format: "bullet" to generate a bullet chart. (See example 1)
• By default, each chart is drawn with zero at the left-most edge and the largest value from its data points as the right-most edge. To use the same value for the right-most edge in all the charts in the column, use the format value "range(0,y)", where y is the value of the right-most edge. Note, however, that if there is a data value that exceeds y, that value is used as the right-most edge for that particular chart. (See example 2)
• From version 5.5, you can use "range(max)" to allow the range to be set by the Klip dynamically, where the largest value among the charts' data points is used as the maximum range value at any given time. (See example 3)
• You can specify the background bar chart's colours by using the format value "colorbands(colour1,colour2,colour3, ...)". Colours must be selected from the following pre-defined colours: violet, blue, turquoise, red, yellow, green, and orange. (See example 4)
• In version 5.5 and later, you can control the order in which the default colours of the bar chart appear by providing the available greyscale values for the format value "colorbands()". The available values are: 0, 20, 40, 60, 80, and 100. (See example 5)
• In version 5.5 and later, the format value "highlight(colour1,colour2)" can be used to specify the bullet colours, where colour1 is applied when the bullet's value is less than the marker value, and colour2 is applied when the bullet value is larger than that of the marker. Colours must be selected from the supplied pre-defined colours: violet, blue, turquoise, red, yellow, green, and orange. (See example 6)
• You can specify the bullet's colours by assigning a colour to a range of values. Colours must be selected from the supplied pre-defined colours. (See example 7)
• To display a legend in the column's header and its tooltip, use legend: "label1,label2,label3", where label1, label2 and label3 (and so on) represent the legend's labels. (See example 8)
• When using the legend property, it is displayed in the column header by default when the Klip is loaded. To change its default display state, use headerlegend: on | off | hidden (on is the default). Note that, regardless of the headerlegend setting, the legend is always displayed in the tooltip of the column header when using the legend property. (See example 9)
• The above settings can be combined as desired. (See example 10)
• Use format: "bullet(x)" to stack bullets, where x is the number of data points to be used for the bullets. (See example 11)
• Use format: "bullet(0)" to display a marker without bullets. (See example 12)
• The height of the chart may be set to height: 1 (default), height: 2 or height: 3 to span 1, 2 or 3 lines within each item, respectively.
• The colours are predetermined by the skin and its hue setting and cannot be specified through the Klip, unless explicitly specified using the pre-defined colours.

Expected data format

See the Expected data format article for details.

How are the data points used to draw a bullet chart?

• Bullet: the first data point(s) in each set of values is used as the bullet. The default is 1 -- when using format: "bullet" or format: "bullet(1)", only the first data point in each data set is used as the bullet value.
• Marker: the data point following the bullet in the set is used as its marker value.
• Bar chart: All of the data point(s) following the marker in the set are used to draw a bar chart.

Here is how the data points are used in case of format: "bullet" or format: "bullet(1)":

Examples

Regardless of how the data source is provided to the chart, the available formatting options are the same.

1. Simple bullet chart

type: graph;
itemcol: 6;
format: "bullet";

You will notice that the marker lines for the two charts are not aligned, even though they are both at 2. This is because the range of each chart is set to the largest value in its source. For example, the largest value for the first item is 12, so its chart spans from 0 to 12. The second chart is spanning from 0 to 10, its largest value. All values in each set are placed relative to this range; therefore, the same values are drawn at different locations.

2. Specifying a static range for the chart

To set the range of all charts in the column, add the format value "range(0,y)" where y is the value for the right-most edge.

type: graph;
itemcol: 7;
format: "bullet,range(0,15)";

3. Specifying a dynamic range for the chart

Available in version 5.5 and later.

To set the range of all charts in the column, add the format value "range(max)". At each refresh, the Klip will automatically detect the largest data value in the column and use it as the value for the right-most edge.

type: graph;
itemcol: 8;
format: "bullet,range(max)";

Because the largest value for the chart is currently 12, the range is automatically set to (0,12). If the largest value becomes 15 at the next refresh, the range will automatically be set to (0,15). If it becomes 8, the range will adjust itself to (0,8).

The "largest value" may be the bullet, marker, or (a segment of) the bar chart.

4. Specifying colours for the bar chart

You can use the format value "colorbands(colour1,colour2,colour3,...) to specify colours for the bar chart in the background. The available colours are: violet, blue, turquoise, red, yellow, green, and orange.

Note that, when using colorbands, the bullet(s) and marker are drawn in black by default. Therefore, it is recommended to be used only with format: "bullet" or format: "bullet(1)".

type: graph;
itemcol: 9;
format: "bullet,colorbands(violet,orange,blue)";

5. Specifying shades of grey for the bar chart

Available in version 5.5 and later.

You can specify the order in which the shades of the default background colours appear with the format value "colorbands()" using greyscale values. The available values are: 0, 20, 40, 60, 80, and 100.

Note that, when using colorbands, the bullet(s) and marker are drawn in black by default. Therefore, it is recommended to be used only with format: "bullet" or format: "bullet(1)".

type: graph;
itemcol: 10;
format: "bullet,colorbands(20,60,100)";

6. Setting the bullet colour depending on its value relative to the marker

Available in version 5.5 and later.

You can specify the bullet colours depending on whether its value is smaller or larger than the marker value using format: "highlight(colour1,colour2)", where colour1 is applied to the bullets whose values are less than the marker, and colour2 is applied to bullets that represent values that are larger than the marker value.

The available colours are: violet, blue, turquoise, red, yellow, green, and orange.

type: graph;
itemcol: 11;
format: "bullet,highlight(red,violet)";

Here, because each chart's bullet value is larger than the marker value, both bullets are displayed in violet.

7. Specifying bullet colours for a range of values

You can specify bullet colours according to a desired range of values. The range of values is defined by adding the <assets> block above your <style> block, and the CSS property asset is used to point to the name of the asset.

The available colours for assets are the same as for the colorbands: violet, blue, turquoise, red, yellow, green, and orange.

<assets>
    <good>green</good>
    <ok>yellow</ok>
    <bad>red</bad>
    
    <asset name="achievement">
    <![CDATA[
        good: value >= 8;
        ok:  value >= 4;
        bad: value < 4;
    ]]>
    </asset>
</assets>

This means, "Use green for any 'good' values, use yellow for the 'ok' values, and use red for the 'bad' values." In the <asset name="achievement"> block, we define good, ok and bad and call this set of value definitions "achievement".

type: graph;
itemcol: 12;
format: "bullet";
asset: "achievement";

This results in this display:

Notice that the first item's bullet for 9 is green because it is larger than 8, which is defined as good.
The second item's bullet is yellow because it is 7, which was set up as ok.

8. Setting up the legend

type: graph;
itemcol: 13;
format: "bullet";
legend: "Performance,Target,Poor,Good,Great";
label: "8. legend";

The above results in the following. Note how the label value ("8. legend") is used as the title of the legend in the tooltip of the column header.

When using the legend property, it is displayed by default as shown above, but you can toggle between it and the column label by right-clicking on the column header:

When the legend is hidden, the first menu option from right-clicking on the column header changes to "Show legend":

To set the default visibility of the legend, see example 9 below.

9. Setting the default visibility of the legend

Use the headerlegend property with one of the following values to set up the column header:

• on - displays the legend and turns on the toggling options in the right-click menu. (Default)
• off - displays the label and turns off the toggling options for the legend display. The legend is only viewable in the tooltip.
• hidden - displays the column header label but gives the toggling options in the right-click menu.

type: graph;
itemcol: 7;
format: "bullet";
legend: "Performance,Target,Poor,Good,Great";
label: "6. legend+headerlegend";
headerlegend: off;

The following screenshot is from using headerlegend: off. Note the lack of "Show legend" option in its right-click menu:

10. Combining several settings

type: graph;
itemcol: 15;
format: "bullet,range(0,15),colorbands(violet,orange,blue)";
legend: "Performance,Target,Poor,Good,Great";
headerlegend: hidden;
label: "15. range+colobands+legend+headerlegend";

11. Displaying bullets for multiple values

For example, using format: "bullet(2)", the data points are used as follows:

And the charts would look like this (note how the bullet values are stacked):

12. Displaying no bullets

If you do not want to display a bullet, use format: "bullet(0)".

Now, the same sets of data are used as follows:

The Klip will look like this:

In the first item, 9 is the marker, with 2, 3, 6 and 12 used in the bar chart; in the second item, 7 is the marker, with the rest of the values used in the bar chart.