Gauge Chart Properties (gaugeProperties)

In this section:

A gauge chart represents one or more values as needles or a single needle and markers on a circular surface. This chart type is typically used by executive dashboard applications.

These properties control the general layout of a gauge chart.

The following code segment shows the default values for the gauge properties:

gaugeProperties: {
   startAngle: 135,  
   endAngle: 45,      
   secondaryNeedlesAsMarkers: false,  
   groupLabel: {
      visible: false,
      font: '10pt Sans-Serif',
      color: 'black'
   },
   totalLabel: {
      visible: false,
      font: '10pt Sans-Serif',
      color: 'black',
      numberFormat: 'auto'
   },
   fill: {
      color: 'transparent'   
   },
   needleBase: {
      size: '6%',  
      color: '#1f77b4',
      border: {
         width: 0,
         color: 'transparent',
         dash: ''
      }
   },
   axisWidth: '22%', 
   axisTickLength: '30%', 
   outerBorder: {
      width: '10%', 
      fill: {
         color: '#1f77b4'
      },
      border: {
         width: 0,
         color: 'transparent',
         dash: ''
      }
   }
},

Note: The yaxis properties control the range and format of values, the format of grid lines, and color bands shown on the gauge axis.


Top of page

x
Controlling the Length of Axis Tick Marks in a Gauge Chart

How to:

The axisTickLength property defines with length of axis tick marks.



x
Syntax: How to Control the Length of Axis Tick Marks in a Gauge Chart
gaugeProperties: {
   axisTickLength: tlength   },

where:

tlength

Can be a number that defines the length in pixels, or a string that includes a percent symbol, enclosed in single quotation marks ('), that defines the width as a percentage of the overall gauge. The default value is '30%'.

Note: Use the yaxis majorGrid property to format the tick marks.



Example: Controlling the Length of Axis Tick Marks in a Gauge Chart

The following request against the GGSALES data source sets the axis tick length to 50%. The y-axis major grid properties set the line style:

GRAPH FILE GGSALES
SUM DOLLARS
BY CATEGORY
WHERE CATEGORY EQ 'Food'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
 
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: { 
    axisTickLength: '50%'},
yaxis: {
   majorGrid: {
      lineStyle: {width: 4,color: 'red',dash: '2 2'}
   }
}
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

The output is:


Top of page

x
Controlling the Width of the Gauge Axis

How to:

The axisWidth property defines the width of the gauge axis.



x
Syntax: How to Control the Width of the Gauge Axis
gaugeProperties: {
   axisWidth: awidth   },

where:

awidth

Can be a number that defines the width in pixels, or a string that includes a percent symbol, enclosed in single quotation marks ('), that defines the width as a percentage of the overall gauge. The default value is '22%'.

Note: Use the yaxis colorBands property to change the default colors on the gauge axis.



Example: Controlling the Axis Width in a Gauge Chart

The following request against the GGSALES data source increases the width of the gauge axis to 50%:

GRAPH FILE GGSALES
SUM DOLLARS
BY CATEGORY
WHERE CATEGORY EQ 'Food'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties:  
    {axisWidth: '50%'}       
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

On the chart output, the color bands that comprise the axis occupy 50% of the gauge area:


Top of page

x
Controlling the Fill Color of the Interior of the Gauge Face

How to:

The fill property controls the fill color of the interior of the gauge face.



x
Syntax: How to Control the Fill Color of the Interior of the Gauge Face
gaugeProperties: {
   fill: {
      color: fcolor   },
}

where:

fcolor

Can be a JSON gradient definition or a string, enclosed in single quotation marks ('), that specifies a color name or numeric specification string, or a gradient definition.

Note: For information about defining colors and gradients, see, Colors and Gradients.



Example: Controlling the Fill Color of the Gauge Face

The following request against the GGSALES data source fills the interior of the gauge face with the color 'lightBlue'.

GRAPH FILE GGSALES
SUM DOLLARS
BY CATEGORY
WHERE CATEGORY EQ 'Food'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: {
   fill: {color: 'lightBlue'}
}
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

The output is:

The following changes the fill color to a linear gradient that transitions from teal to cyan:

gaugeProperties: {
   fill: {color: 'linear-gradient(0%,0%,100%,0%, 20% teal, 95% cyan)'}
},

The output is:


Top of page

x
Formatting the Group Label in a Gauge Chart

How to:

The groupLabel properties control the visibility and format of the group label in a gauge chart.



x
Syntax: How to Format the Group Label in a Gauge Chart
gaugeProperties: {
   groupLabel: {
      visible: boolean,
      font: 'fstring',
      color: 'cstring'
   },
},

where:

boolean

Valid values are:

  • true, which makes the group label visible. This is the default value.
  • false, which makes the group label not visible.
'fstring'

Is a string that defines the size, style, and, typeface of the label. The default value is '10pt Sans-Serif'.

'cstring'

Is a string that defines the color of the label. The default value is 'black'.

Note: The gaugeProperties groupLabel property does not change the text that displays for the group label. The general groupLabels property does that. The default group label is the sort field value for which the gauge is drawn.



Example: Formatting the Gauge Group Label

The following request against the GGSALES data source makes the group label red and bold-italic 14pt Sans-Serif:

GRAPH FILE GGSALES
SUM DOLLARS
BY CATEGORY
WHERE CATEGORY EQ 'Food'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: {
   groupLabel: {
      font: 'bold italic 14pt Sans-Serif',
      color: 'red'     
   },
}
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

The output is:


Top of page

x
Formatting the Base of the Gauge Needle

How to:

The needleBase properties control the format of the base of the gauge needle.



x
Syntax: How to Format the Base of the Gauge Needle
gaugeProperties: {
   needleBase: {
      size: nsize,  
      color: ncolor,
      border: {
         width: bnumber,
         color: 'bcstring',
         dash: 'dstring'
      }
   },
},

where:

nsize

Can be a number that defines the radius in pixels, or a string that includes a percent symbol, enclosed in single quotation marks ('), that defines the radius as a percentage of the overall gauge. The default value is '6%'.

'ncolor'

Can be a JSON gradient definition, or a string, enclosed in single quotation marks ('), that defines a color name or numeric specification string, or a gradient defined as a string. For information about specifying colors and gradients, see Colors and Gradients.

bnumber

Is a number of pixels that defines the width of the border around the needle base. The default value is zero (no border).

'bcstring'

Is a color defined by a name or numeric specification string. The default value is 'transparent' (no border).

'dstring'

Is a string that defines the border dash style. The default value is '', which produces a solid line. Use a string of numbers that defines the width of a dash followed by the width of the gap between dashes.



Example: Formatting the Gauge Needle Base

The following request against the GGSALES data source makes the gauge needle base red, with a radius of 10 pixels, and a green dashed border with a width of 3 pixels:

GRAPH FILE GGSALES
SUM DOLLARS 
BY CATEGORY
WHERE CATEGORY EQ 'Food'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: {
 groupLabel: {visible:false},  
   needleBase: {
      size: 10,  
      color: 'red',
      border: {
         width: 3,
         color: 'green',
         dash: '1 1'     
      }
   }
}
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

The output is:


Top of page

x
Formatting the Outer Border in a Gauge Chart

How to:

The outerBorder properties control the format of the outer border in a gauge chart.



x
Syntax: How to Format the Outer Border in a Gauge Chart
gaugeProperties: {
   outerBorder: {
      width: owidth,
      fill: {
         color: fcolor,
      },
      border: {
         width: bnumber,
         color: 'bcstring',
         dash: 'dstring' 
      }
   }
},

where:

owidth

Can be a number that defines the width of the outer border ring in pixels, or a string that includes a percent symbol, enclosed in single quotation marks ('), that defines the outer border ring as a percentage of the overall gauge. The default value is '10%'.

'fcolor'

Is a JSON gradient definition or a string, enclosed in single quotation marks ('), that specifies a color name or numeric specification string, or a gradient defined as a string. The default value is '#1f77b4'. For information about specifying colors and gradients, see Colors and Gradients.

bnumber

Is a number of pixels that defines the width of the outer border. The default value is zero (no border).

'bcstring'

Is a color defined by a name or numeric specification string. The default value is 'transparent' (no border).

'dstring'

Is a string that defines the border dash style. The default value is '', which produces a solid line. Use a string of numbers that defines the width of a dash followed by the width of the gap between dashes.



Example: Formatting the Outer Border of a Gauge Chart

The following request against the GGSALES data source makes the outer border of the gauge chart 20 pixels wide, with a fill color that is a linear gradient that transitions from antique white to pink to light blue. The border of the outer border is an 8 pixel wide pink dashed line:

GRAPH FILE GGSALES
SUM DOLLARS 
BY CATEGORY
WHERE CATEGORY EQ 'Food'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: {
 groupLabel: {visible:false},  
  outerBorder: {
      width: 20, 
      fill: {color: 'linear-gradient(0%,0,100%,0, 0 antiquewhite, 0.5 pink,
      1 lightblue)'},
      border: {width: 8,color: 'pink',dash: '2 2'}    
   }
}
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

The output is:


Top of page

x
Drawing Secondary Gauge Needles as Markers

How to:

When a gauge includes multiple needles (multiple measures), use the secondaryNeedlesAsMarkers property to draw secondary needles as markers.



x
Syntax: How to Draw Secondary Gauge Needles as Markers
gaugeProperties: {
   secondaryNeedlesAsMarkers: boolean,
},

where:

boolean

Valid values are:

  • true, which draws the secondary needles as markers.
  • false, which draws multiple needles. The default value is false.

Note: When secondaryNeedlesAsMarkers is true, use the series:marker property to control the size and format of the markers.



Example: Drawing Secondary Gauge Chart Needles as Markers

The following request against the GGDEMOG data source draws the secondary needles as needles:

GRAPH FILE GGDEMOG
SUM HH MEDHHI98 
MALEPOP98 FEMPOP98                                                  
P15TO1998 P20TO2998 
P50TO6498 
BY ST
WHERE ST EQ 'NY'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: {
  groupLabel: {visible:false},  
  secondaryNeedlesAsMarkers: false    
}
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END
 

The output is:

The following version of the request, draws the secondary needles as markers, and sets marker shapes, sizes, borders and colors for them. To make the markers more visible, the axis width is set to zero. Notice that series 0 is the primary needle, and is still drawn as a needle:

GRAPH FILE GGDEMOG
SUM HH MEDHHI98 
MALEPOP98 FEMPOP98                                                  
P15TO1998 P20TO2998 
P50TO6498 
BY ST
WHERE ST EQ 'NY'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: {
  groupLabel: {visible:false}, 
  axisWidth: 0, 
  secondaryNeedlesAsMarkers: true       
},
series: [
{series: 0, color: 'red',},
{series: 1, color: 'tan',marker: {shape: 'circle', size: 12, border: 
{width: 1, color: 'orange'}}},
{series: 2, color: 'blue',marker: {shape: 'triangle', size: 12, border: 
{width: 1, color: 'black'}}},
{series: 3, color: 'orange',marker: {shape: 'diamond', size: 12, border: 
{width: 1, color: 'grey'}}},
{series: 4, color: 'purple',marker: {shape: 'pirateCross', size: 12, 
border: {width: 1, color: 'black'}}},
{series: 5, color: 'pink',marker: {shape: 'hourglass', size: 12, 
border: {width: 1, color: 'purple'}}},
{series: 6, color: 'limegreen',marker: {shape: 'house', size: 12, border: 
{width: 1, color: 'black'}}}
]   
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

The output is:


Top of page

x
Controlling the Start and End Angles of a Gauge Chart Axis

How to:

The startAngle and endAngle properties control the start and end angles of the gauge value band. Angles are defined in degrees. Positive angles draw clockwise, negative angles draw counter clockwise. Zero will start or end the band at the 3 o'clock position. 90 will start or end the band at the 6 o'clock position. -90 specifies the 12 o'clock position.

Note: The gauge chart axis is also called a value band.



x
Syntax: How to Control the Start and End Angles of a Gauge Chart Axis
gaugeProperties: {
   startAngle: snumber,  
   endAngle: enumber},

where:

snumber

Is a number that defines the angle (in degrees) at which to start the gauge value band. The default value is 135.

enumber

Is a number that defines the angle (in degrees) at which to end the gauge value band. The default value is 45.



Example: Controlling the Start and End Angles in the Gauge Chart Axis

The following request against the GGSALES data source uses the default start angle (135) and end angle (45) for the gauge chart value band. The axis width is set to 2 pixels:

GRAPH FILE GGSALES
SUM DOLLARS 
BY CATEGORY
WHERE CATEGORY EQ 'Food'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: {
 groupLabel: {visible:false},  
 axisWidth: 2,
   startAngle: 135,
   endAngle: 45      
}
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

The output is:

Changing the start and end angles to zero (0), makes the value band a complete circle:


Top of page

x
Formatting a Gauge Chart Total Label

How to:

The totalLabel properties control the visibility and format of the total label in a gauge chart.



x
Syntax: How to Format a Gauge Chart Total Label
gaugeProperties: {
   totalLabel: {
      visible: boolean,
      font: 'fstring',
      color: 'cstring'
      numberFormat: nformat   },
},

where:

boolean

Valid values are:

  • true, which makes the label visible.
  • false, which makes the label not visible. This is the default value.
'fstring'

Is a string that defines the size, style, and, typeface of the label. The default value is '10pt Sans-Serif'.

'cstring'

Is a string that defines the color of the label using a color name or numeric specification string. The default value is 'black'.

For information about specifying colors, see Colors and Gradients.

nformat

Can be specified as a JSON object, a format string, or a user-defined function. The default value is 'auto'. For information on specifying number formats, see Formatting Numbers.



Example: Formatting a Gauge Chart Total Label

The following request against the GGSALES data source makes the gauge chart total label visible, with a red 12pt Courier font, and a currency number format:

GRAPH FILE GGSALES
SUM DOLLARS 
BY CATEGORY
WHERE CATEGORY EQ 'Food'
ON GRAPH PCHOLD FORMAT JSCHART
ON GRAPH SET LOOKGRAPH GAUGE1
ON GRAPH SET STYLE *
*GRAPH_JS
gaugeProperties: {
 groupLabel: {visible:false},  
   totalLabel: {
   visible: true,font: '12pt Courier',color: 'red',
   numberFormat: {mode: 'currency'}     
 }
}
*END
INCLUDE=ENIADefault_combine.sty,$
ENDSTYLE
END

The output is:


WebFOCUS