/
Gauges (Quick Reference)

Gauges (Quick Reference)

Gauges are useful to indicate sizes of fractions, or how well a measurement is performing. Gauges can be created easily with ResultGauge, or with high level of flexibility with Highcharts.

Circular Arc

The Circular Arc Gauge is useful for indicating a fraction.

360 arc

Gauge.groovy

ResultHighchart arcGauge360( String title, String unit, BigDecimal value, BigDecimal minValue, BigDecimal maxValue, String color ) { def chart = api.buildHighchart([ title: [ text: title ], chart : [type: 'solidgauge'], credits : [enabled: false], yAxis : [ min : minValue, max : maxValue, tickPositions: [], lineWidth: 0, ], series : [[ name : title, data : [[ y: value, color: color, ]], tooltip : [valueSuffix: " $unit"], // The value label in the center dataLabels: [ format: """<span style="font-size:24px">{y:.1f} $unit</span>""" ], ]], // Appearance pane : [ background: [ backgroundColor: 'rgba(0,0,0,0.06)', innerRadius : '60%', outerRadius : '100%', shape : 'arc', borderWidth: 0, ] ], // Disable the border around the centered value label plotOptions: [ solidgauge: [ dataLabels: [ borderWidth: 0 ] ] ], ]) chart.addModule('solid-gauge') return chart }

Result Gauge

For building a gauge quick and easy, the ResultGauge class can come in handy.

result gauge

However, the ResultGauge has several disadvantages compared to Highcharts gauges:

  • ResultGauge cannot be used in dashboards.

  • ResultGauge is not very customizable. You can define the value range and colors of the so-called sections.

  • When used in documents – such as Quotes – ResultGauge has a tiny size.

def red = 'rgba(223, 83, 83, 0.22)' def yellow = 'rgba(221, 223, 13, 0.22)' def green = 'rgba(85, 191, 59, 0.22)' def gauge = api.newGauge() gauge.value = value gauge.min = minValue gauge.max = maxValue gauge.addSector(redThreshold, red) gauge.addSector(yellowThreshold, yellow) gauge.addSector(null, green) return gauge

Gauges with Alerts Thresholds

Like alerts, gauges can convey indication of how well something is performing. For example, how much profit is being made from a quote item. In this case, it can be useful to define the sectors according to the alert thresholds:

result gauge

Gauge.groovy

ResultGauge resultGaugeAlert( BigDecimal value, BigDecimal redLowerBound, BigDecimal redUpperBound, BigDecimal yellowUpperBound ) { def gauge = api.newGauge() def minValue = redLowerBound def maxValue = yellowUpperBound + Math.abs(yellowUpperBound - redLowerBound) as BigDecimal def red = 'rgba(223, 83, 83, 0.22)' def yellow = 'rgba(221, 223, 13, 0.22)' def green = 'rgba(85, 191, 59, 0.22)' gauge.min = minValue gauge.max = maxValue gauge.value = value gauge.addSector(redUpperBound, red) gauge.addSector(yellowUpperBound, yellow) gauge.addSector(null, green) return gauge }

Semi Circular Arc with Gradient Alert Colors

The Semi Circular Arc is used to indicate fractions. To inform end users how well a certain measurement is performing, it gradually shifts color as the value increases/decreases.

arch

Gauge.groovy

ResultHighchart arcGauge180Gradient( String title, String unit, BigDecimal value, BigDecimal minValue, BigDecimal maxValue, BigDecimal errorStopValue, BigDecimal warningStopValue, BigDecimal successStopValue ) { def colors = libs.Library_CSS.Color def stops = [ [transformStopValue(errorStopValue, minValue, maxValue), colors.ERROR], [transformStopValue(warningStopValue, minValue, maxValue), colors.WARNING], [transformStopValue(successStopValue, minValue, maxValue), colors.SUCCESS], ] def chart = api.buildHighchart([ title: [ text: title ], chart : [type: 'solidgauge'], credits : [enabled: false], yAxis : [ min : minValue, max : maxValue, stops : stops, // Only indicate max and min values, no intermediate values tickPositions: [minValue, maxValue], minorTickInterval: null, lineWidth: 0, tickWidth: 0, labels : [ y: 24, format: "{value:.1f} $unit", ], ], series : [[ name : title, data : [value], tooltip : [valueSuffix: " $unit"], // The value label in the center dataLabels: [format: """<span style="font-size:24px">{y:.1f} $unit</span>"""], ]], // Appearance pane : [ center : ['50%', '85%'], size : '140%', startAngle: -90, endAngle : 90, background: [ backgroundColor: colors.FAINT_GREY, innerRadius : '60%', outerRadius : '100%', shape : 'arc', borderWidth: 0, ] ], // Disable the border around the value label plotOptions: [solidgauge: [dataLabels: [borderWidth: 0]]], ]) chart.addModule('solid-gauge') return chart } /** * Transforms the stop value to a number between 0 and 1. */ BigDecimal transformStopValue(BigDecimal threshold, BigDecimal minValue, BigDecimal maxValue) { return (threshold - minValue) / (maxValue - minValue) }
def gauges = libs.Library_Charts.Gauge String title = 'Some Percentage' String unit = '%' BigDecimal gaugeValue = input.gaugeValue ?: 0 BigDecimal minValue = -1 BigDecimal maxValue = 1 BigDecimal errorThreshold = -0.5 BigDecimal warningThreshold = 0 BigDecimal successThreshold = 0.5 return gauges.buildGauge( title, unit, gaugeValue * 100, minValue * 100, maxValue * 100, errorThreshold * 100, warningThreshold * 100, successThreshold * 100 )

Speedometer

Highcharts allow for a large degree of freedom. The example below shows a configuration that results in a speedometer:

speedometer

Gauge.groovy

ResultHighchart speedometer( String title, String unit, BigDecimal value, BigDecimal redLowerBound, BigDecimal redUpperBound, BigDecimal yellowUpperBound ){ def colors = libs.Library_CSS.Color def minValue = redLowerBound def maxValue = yellowUpperBound + Math.abs(yellowUpperBound - redLowerBound) as BigDecimal def chart = api.buildHighchart([ chart: [ type: 'gauge', plotBackgroundColor: null, plotBackgroundImage: null, plotBorderWidth: 0, plotShadow: false ], credits : [enabled: false], title: [ text: title ], pane: [ startAngle: -150, endAngle: 150, background: [[ backgroundColor: [ linearGradient: [ x1: 0, y1: 0, x2: 0, y2: 1 ], stops: [ [0, '#FFF'], [1, '#333'] ] ], borderWidth: 0, outerRadius: '109%' ], [ backgroundColor: [ linearGradient: [ x1: 0, y1: 0, x2: 0, y2: 1 ], stops: [ [0, '#333'], [1, '#FFF'] ] ], borderWidth: 1, outerRadius: '107%' ], [ // default background ], [ backgroundColor: '#DDD', borderWidth: 0, outerRadius: '105%', innerRadius: '103%' ]] ], // the value axis yAxis: [ min: minValue, max: maxValue, minorTickInterval: 'auto', minorTickWidth: 1, minorTickLength: 10, minorTickPosition: 'inside', minorTickColor: '#666', tickPixelInterval: 30, tickWidth: 2, tickPosition: 'inside', tickLength: 10, tickColor: '#666', labels: [ step: 2, rotation: 'auto' ], title: [ text: unit ], plotBands: [[ from: minValue, to: redUpperBound, color: colors.ERROR, ], [ from: redUpperBound, to: yellowUpperBound, color: colors.WARNING ], [ from: yellowUpperBound, to: maxValue, color: colors.SUCCESS ]] ], series: [[ name: title, data: [value], dataLabels: [ format: """{y:.1f} $unit""" ], tooltip: [ valueSuffix: " $unit" ] ]] ]) return chart }

Found an issue in documentation? Write to us.