JSignage:Graph:Linear gauges

From SpinetiX Support Wiki

Jump to: navigation, search

This page is related to jSignage Graph API.

Introduction

A basic linear gauge represents a single data item by positioning an indicator along a vertical or horizontal line to point to the current data value. A linear bar gauge represents one or more data item values by filling a progress bar with a solid color or a gradient from the baseline to the current value along a vertical or horizontal line.

  • The main axis is a continuous axis representing the possible values for the data item(s). An alternative axis might also be used to represent the same values with alternative units.
  • One or more "threshold" bars can be drawn next to the axes.
  • The fill color of each bar in a group or stack can be adjusted separately.
  • If labels are provided then a legend box can be included in the layer next to the graph area.
  • Text can be drawn at configurable positions in the gauge. This is can be static text or text representing the current value with a configurable formatting (only available for singular data).
  • If the gauge is made dynamic, its value(s) can change in real-time, with or without an animation of the bars and indicator (if any).

Classification

Data size Basic linear gauges Linear bar gauges
Single value $.Graph.horizontalGauge()
$.Graph.verticalGauge() 		$.Graph.horizontalBarGauge()
$.Graph.verticalBarGauge()
Multiple values $.Graph.groupedHorizontalBarGauge()
$.Graph.groupedVerticalBarGauge()
$.Graph.stackedHorizontalBarGauge()
$.Graph.stackedVerticalBarGauge()
$.Graph.stackedAndGroupedHorizontalBarGauge()
$.Graph.stackedAndGroupedVerticalBarGauge()

Gallery of linear gauges

.Graph.horizontalGauge()

$.Graph.horizontalGauge( attributes );

Returns: jSignage Object

Description

Draws a horizontal gauge layer displaying a single data item by positioning an indicator along a horizontal axis defined by the user, to point to the current data value. An indicator is always present on this type of gauge and a thresholds bar is typically used to represent the expected normal range of the value.

Parameters

.Graph.verticalGauge()

$.Graph.verticalGauge( attributes );

Returns: jSignage Object

Description

Draws a vertical gauge layer displaying a single data item by positioning an indicator along a vertical axis defined by the user, to point to the current data value. An indicator is always present on this type of gauge and a thresholds bar is typically used to represent the expected normal range of the value.

Parameters

.Graph.horizontalBarGauge()

$.Graph.horizontalBarGauge( attributes );

Returns: jSignage Object

Description

Draws a horizontal bar gauge layer displaying a single data item by filling a progress bar with a solid color or a gradient from the baseline to the current value along a horizontal axis defined by the user. The color of the bar can be made dependent on the current value according to a defined set of colors for different thresholds. The bar can be customized to a set of segments, each with its own size and color. An indicator is optional for this type of gauge.

Parameters

  • attributes
    Type: Plain Object.
    The horizontal bar gauge layer attributes, containing any of the common attributes of linear gauges and the following attributes:
    • data (required)
      Type: Number. Default: 0.
      The value to be displayed.
    • bar
      Type: Plain Object.
      An optional gauge thresholds bar styling object to customize the bar appearance (which by default is a solid filled rectangle).
    • color
      Type: Color.
      Defines the color to be used for a solid fill of the bar.
    • colors
      Type: Array.<Plain Object>.
      Array of objects that define different colors that the bar might have depending on data value to be displayed. Each object has the following properties:
      • color
        Type: Color.
        Defines the color to apply within the range of values.
      • from
        Type: Number. Default: The to value of the previous range (if any) or dataMin.
        Minimum value for which this color applies.
      • to
        Type: Number. Default: The from value of the next range (if any) or dataMax.
        Maximum value (not inclusive) to which this color applies.
    • indicator
      An indicator styling object.

.Graph.verticalBarGauge()

$.Graph.verticalBarGauge( attributes );

Returns: jSignage Object

Description

Draws a vertical bar gauge layer displaying a single data item by filling a progress bar with a solid color or a gradient from the baseline to the current value along a vertical axis defined by the user. The color of the bar can be made dependent on the current value according to a defined set of colors for different thresholds. The bar can be customized to a set of segments, each with its own size and color. An indicator is optional for this type of gauge.

Parameters

.Graph.groupedHorizontalBarGauge()

$.Graph.groupedHorizontalBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more horizontal bar gauges grouped together. The fill color of each bar can be adjusted separately. This type of gauge cannot display an indicator.

Parameters

.Graph.groupedVerticalBarGauge()

$.Graph.groupedVerticalBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more vertical bar gauges grouped together. The fill color of each bar can be adjusted separately. This type of gauge cannot display an indicator.

Parameters


.Graph.stackedHorizontalBarGauge()

$.Graph.stackedHorizontalBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more horizontal bar gauges stacked together. The fill color of each bar can be adjusted separately. This type of gauge cannot display an indicator.

Parameters

  • attributes
    Type: Plain Object.
    The stacked horizontal bar gauge layer attributes, containing any of the common attributes of linear gauges and the following attributes:
    • data (required)
      Type: Array.<Number>. Default: [].
      Array of numbers, where each value corresponds to a bar gauge.
    • colors
      Type: Array.<Color>.
      Defines the colors to be used for a solid fill of each bar.
    • labels
      Type: Array.<String>.
      Defines the labels to be used for each bar gauge.

.Graph.stackedVerticalBarGauge()

$.Graph.stackedVerticalBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more vertical bar gauges stacked together. The fill color of each bar can be adjusted separately. This type of gauge cannot display an indicator.

Parameters

.Graph.stackedAndGroupedHorizontalBarGauge()

$.Graph.stackedAndGroupedHorizontalBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more horizontal bar gauges stacked and grouped together. This type of gauge cannot display an indicator.

Parameters

  • attributes
    Type: Plain Object.
    The stacked and grouped horizontal bar gauge layer attributes, containing any of the common attributes of linear gauges and the following attributes:
    • data (required)
      Type: Array.<Array.<Number>>. Default: [].
      2D array of numbers, where each set of values corresponds to a group of stacked bar gauges and each value inside corresponds to a bar gauge. The first dimension is the position along the major axis (i.e. the group), the second dimension is the position within the stack.
    • colors
      Type: Array.<Color>.
      Defines the colors to be used for a solid fill of each bar.
    • labels
      Type: Array.<String>.
      Defines the labels to be used for each bar gauge.

.Graph.stackedAndGroupedVerticalBarGauge()

$.Graph.stackedAndGroupedVerticalBarGauge( attributes );

Returns: jSignage Object

Description

Draws a layer with one or more vertical bar gauges stacked and grouped together. This type of gauge cannot display an indicator.

Parameters

Common attributes

See also Graph styling attributes page.

The following attributes are common to linear gauges:

  • altAxis
    Type: Plain Object. Default: null.
    Continuous axis object configuring an alternative axis. The default position for the alternative axis is 'top' for horizontal gauges and 'right' for vertical gauges.
  • animationDur
    Type: Number or String. Default: 0 (no animation).
    Defines the animation time as a number of seconds or as a text (e.g. '500ms'). The dynamic attribute must be set to true to be considered.
  • axis
    Type: Plain Object.
    Continuous axis object configuring the main axis. Note that for bar gauges, the axis line itself is not displayed by default and axis.axis must be set to true to draw it. Two additional axis properties are specific to linear gauges:
    • offset
      Type: Number or String. Default: 0.
      Offset from the selected position in pixels or as a percentage of the layer size.
    • position
      Type: Number or String. Default: 'bottom' for horizontal gauges, 'left' for vertical gauges.
      Determines on which side of the bar the axis is drawn. It can be either 'top' or 'bottom' for horizontal gauges, and 'left' or 'right' for vertical gauges.
  • axisStrokeStyle
    Type: Plain Object.
    Stroke styling object which serves as a default for drawing axis lines.
  • backColor
    Type: Color. Default: null.
    Defines the color to be used for a solid fill of the bar gauge background area. This doesn't apply for basic linear gauges.
  • barWidth
    Type: Number or String. Default: '100%'.
    Width occupied by the bar either in pixels or as a percentage relative to the maximum space available. This doesn't apply for basic linear gauges.
  • baselineStrokeStyle
    Type: Plain Object.
    Stroke styling object which serves as a default for drawing the baseline.
  • chartArea
    Type: Plain Object. Default: null.
    Object with top, left, width and height attributes to define the position of the gauge bar. By default the chart will occupy as much space as possible without overlapping the legend box.
  • dataMax
    Type: Number. Default: 1.
    Maximum value for data items to be displayed on the axis.
  • dataMin
    Type: Number. Default: 0.
    Minimum value for data items to be displayed on the axis.
  • dynamic
    Type: Boolean. Default: false.
    Defines whether the gauge is dynamic. When set to true, the gauge can be animated and updated (i.e. the gauge layer has an update() function; calling this method updates the gauge with new data, then redraws it with or without an animation depending on animation parameters).
  • fontFamily, fontSize, fontStyle, fontVariant, fontWeight
    Type: String or Number.
    Default text styling attributes for gauge text, axis text and legend. The fontSize is set by default to 15% of layer size.
  • gridlinesStrokeStyle
    Type: Plain Object.
    Stroke styling object which serves as a default for drawing the grid lines.
  • legend
    Type: Plain Object.
    Legend styling object.
  • text
    Type: Plain Object or Array.<Plain Object>.
    One or more text description objects with the following properties:
    • align
      Type: String. Default: 'center' except for text left or right of a bar.
      Text horizontal alignment with regards to reference point, one of 'left', 'right' or 'center'.
    • baseline
      Type: String. Default: 'middle' except for text above or below a bar.
      Specifies the position of the text baseline, one of 'top', 'bottom' or 'middle'.
    • format
      Type: String. Default: default numerical format of the chart locale.
      Number format string to display the current data as text.
    • offset
      Type: Number or String.
      Offset from the chosen position in pixels or percentage of layer size.
    • position
      Type: String.
      Position of the text relative to the chart area, one of 'left', 'right', 'top', 'bottom' or 'center'.
    • style
      Type: Plain Object.
      Text styling object to override textStyle.
    • text
      Type: String.
      Static text to display. Use of the format property will override it.
    • where
      Type: Number or String.
      If the text position is on the long size of the chart, i.e top or bottom for horizontal gauges, respectively left or right for vertical gauges, this property defines the linear position of the text reference point on the main axis. This is either a valid numerical value on the main axis, 'center' or 'indicator' (which means that the text is at the same linear position as the indicator).
  • textStyle
    Type: Plain Object.
    Default text styling attributes for chart text.
  • thresholds
    Type: Plain Object or Array.<Plain Object>.
    One or more gauge thresholds bar styling objects to display one or more bars with thresholds indications.

Common functions

.update()

gauge_layer.update( data );

Returns: undefined

Description

Updates the gauge data attribute, then redraws the gauge layer, with or without an animation of the bars and indicator (if any), depending on animation parameters. This function becomes available for the gauge layer when the dynamic gauge attribute is set to true.

  • The type of the data parameter must be identical to the data attribute detailed under each linear gauge function.
  • See an example of usage for this function.

Examples

Horizontal gauge
Horizontal gauge
// draw a horizontal gauge
$.Graph.horizontalGauge( {
    data: 75, dataMax: 100,
    left: 60, width: 1160, height: 720, fontSize: 60,
    indicator: {
        color: '#000', position: 'bottom', 
        shape: 'triangle', length: '10%', width: '20%'
    },
    axis: {
        position: 'bottom', textPlacement: 'none', minorTickMarks: true,
        tickMarks: { length: '10%' }
    },
    altAxis: {
        position: 'top', offset: '7%',
        textStyle: { color: '#888' }
    },
    axisStrokeStyle: { color: '#888' },
    text: {
        position: 'bottom', offset: '10%', where: 'indicator',
        style: { fontSize: 80 }
    },
    thresholds: {
        position: 'top', size: '10%',
        zones: [ { to:  40, color: '#0e0'}, 
                 { to:  80, color: '#fe0'}, 
                 { to: 100, color: '#e00'}
        ]
    }
} ).addTo('svg');

Vertical gauge
Vertical gauge
// draw a vertical gauge
$.Graph.verticalGauge( {
    data: 75, dataMax: 100,
    fontSize: 50,
    indicator: {
        color: '#000', position: 'right', offset: '28%',
        shape: 'triangle', length: '10%', width: '20%'
    },
    axis: {
        position: 'left', textPlacement: 'outside', 
        tickMarks: {  placement: 'inside', length: '15%' },
        minorTickMarks: { length: '65%' }
    },
    axisStrokeStyle: { color: '#000' },
    text: {
        position: 'right', offset: '40%', where: 'indicator',        
        style: { fontSize: 80 }
    },
    thresholds: {
        position: 'right', size: '10%', startSize: 0, offset: '18%',
        zones: [ { to:  40, color: '#0e0'}, 
                 { to:  80, color: '#fe0'}, 
                 { to: 100, color: '#e00'}
        ]
    }
} ).addTo('svg');

Horizontal bar gauge with indicator
Horizontal bar gauge with indicator
// draw a horizontal bar gauge with indicator
$.Graph.horizontalBarGauge( {
    data: 75, dataMax: 100,
    top: 200, left: 60, width: 1160, height: 320,
    backColor: '#aaa',
    dynamic: true, animationDur: '500ms',
    indicator: {
        color: '#000', position: 'top', placement: 'outside',
        shape: 'arrow', length: '25%'
    },
    axis: {
        textStyle: { color: '#aaa', fontSize: 40 },
        tickMarks: { length: '20%', strokeStyle: { lineWidth: 4 } },
        minorTickMarks: { 
            count: 3, length: '75%', 
            strokeStyle: { lineWidth: 2 } 
        },
        gridlines: { strokeStyle: { color: 'white', lineWidth: 2 } },
        minorGridlines: { count: 3 }
    },
    axisStrokeStyle: { color: '#aaa' },
    text: {
        position: 'top', offset: '25%', where: 'indicator',        
        style: { fontWeight: 'bold', fontSize: 60 }
    }
} ).addTo('svg');

Vertical bar gauge with dynamic colors
Vertical bar gauge with dynamic colors
// draw a vertical bar gauge with dynamic colors
var gaugeChart = 
$.Graph.verticalBarGauge( {
    data: 75, dataMax: 100,
    left: 470, width: 340, height: 720,
    dynamic: true, animationDur: '500ms',
    axis: {
        textStyle: { color: '#888', fontSize: 30 },
        tickInterval: 10,
        tickMarks: { length: '10%', strokeStyle: { lineWidth: 2 } },
        minorTickMarks: { count: 4 }
    },
    altAxis: {
        position: 'right', textPlacement: 'none', 
        tickInterval: 10,
        tickMarks: { length: '10%', strokeStyle: { lineWidth: 2 } },
        minorTickMarks: { count: 4 }
    },
    axisStrokeStyle: { color: '#888' },
    colors: [ { color: '#0e0', to: 40 },
              { color: '#fe0', to: 80 }, 
              { color: '#e00' } 
    ],
    text: {
        position: 'center', where: 'indicator', format: '#',       
        style: { fontWeight: 'bold', fontSize: 80 }
    }
} ).addTo('svg');

// update the gauge data every 2s with a random number
$.setInterval( function() {
    gaugeChart.update( Math.random()*100 );
}, 2000 );

Vertical grouped bar gauge with custom bar
Grouped linear bar gauge with custom bar
// draw a vertical grouped bar gauge with custom bar
$.Graph.groupedVerticalBarGauge( {
    data: [ 87.6, 75 ], 
    dataMax: 100,
    top:20, left: 470, width: 340, height: 680,
    fontSize: 40, 
    dynamic: true, animationDur: '500ms',
    altAxis: { position: 'right' },
    backColor: '#444',
    bar: {
        step: 4, stepSize: 0.6,
        zones: [ { color: '#0e0', to: 40 }, 
                 { color: '#fe0', to: 80 }, 
                 { color: '#e00' } 
        ] 
    },
    barWidth: '80%'
} ).addTo('svg');

Horizontal stacked bar gauge
Stacked linear bar gauge
// draw a horizontal stacked bar gauge
$.Graph.stackedHorizontalBarGauge( {
    data: [ 45, 30, 15 ], 
    dataMax: 100,
    top: 200, left: 60, width: 1160, height: 320,
    fontSize: 40, 
    backColor: '#aaa',
    axis: {
        textStyle: { color: '#aaa', fontSize: 40 },
        tickMarks: { length: '20%', strokeStyle: { lineWidth: 4 } },
        minorTickMarks: { 
            count: 3, length: '75%',
            strokeStyle: { lineWidth: 2 } 
        },
        gridlines: { strokeStyle: { color: 'white', lineWidth: 2 } },
        minorGridlines: { count: 3 }
    },
    axisStrokeStyle: { color: '#aaa' }
} ).addTo('svg');

Retrieved from "https://support.spinetix.com/w/index.php?title=JSignage:Graph:Linear_gauges&oldid=9408"
This page was last modified on 13 May 2015, at 11:38.