JSignage:Graph:Pie and donut charts

This page is related to jSignage Graph API.

Introduction

Pie and donut charts represent data as slices, where the size of each slice is determined by the slice value relative to the sum of the values of all slices. These charts are usually shaped as either full circle (360°) or semi-circular, although the start and end angles are fully customizable. The donut charts are in fact pie charts with a hole in the center.

To create a pie / donut chart layer, use $.Graph.pieChart() function.

Gallery of pie and donut charts

• 

  Pie chart

• 

  Donut chart

• 

  Semicrcular donut chart

.Graph.pieChart()

$.Graph.pieChart( attributes );

Returns: jSignage Object

Description

Draws a pie / donut chart layer.

• To obtain a donut shaped chart, make sure to specify the pieHole attribute.
• The fill color and stroke style of each slice can be adjusted separately. The fill is either a solid uniform color or a radial luminosity gradient.
• The text inside a slice is configurable among the following options: no text, label, value or percentage. Likewise the text outside / next to a slice is configurable with the same options. If labels are provided then a legend box can be included in the layer next to the graph area.
• A slice labeled 'Other' is automatically added to the chart if some values are too small to be represented in their own slice.
• It's possible to offset a slice in order to highlight it further.

Parameters

• attributes

  Type: Plain Object.

  Contains the pie chart layer attributes detailed below. See also Graph styling attributes page.

Attributes

• data (required)

  Type: Array.<Number>.

  Array of numbers, where each value corresponds to a slice of the pie.

• borderSize

  Type: Number. Default: 2% of pie radius;

  Additional space in pixels left empty between the slices. 0 means the slices are contiguous.

• chartArea

  Type: Plain Object.

  Object with top, left, width and height attributes to define the position of the pie chart within the layer. By default the chart will occupy as much space as possible without overlapping the legend box.

• colors

  Type: Array.<Color>. Default: $.Graph.baseColors

  Array of colors, where each value corresponds to a slice of the pie.

• endAngle

  Type: Number. Default: startAngle;

  End angle of the pie. If equal to the start angle the pie is a full circle.

• fontFamily, fontSize, fontStyle, fontVariant, fontWeight

  Type: String or Number.

  Default text styling attributes for slice text and legend. The fontSize is set by default to 10% of the pie radius.

• labels

  Type: Array.<String>. Default: [ '1', '2', '3', '4', ... ]

  Array of labels, where each value corresponds to a slice of the pie.

• legend

  Type: Plain Object. Default: A legend box styling object displaying the legend on the right side of the graph.

  Legend box styling object or null to disable the legend box. Note that the legend box will reduce the graph area when enabled.

• pieHole

  Type: Number. Default: 0.

  Fraction between 0 (no hole) and 1 (exclusive) for an hollowed out center inside the pie chart. A value of 0.4 is typically used to produce a donut chart.

• pieResidueSliceColor

  Type: Color. Default: '#ccc'.

  Color of the residual slice.

• pieResidueSliceLabel

  Type: String. Default: 'Other'.

  Label associated to the residual slice.

• reverseCategories

  Type: Boolean. Default: false.

  Weather the pie is drawn anticlockwise (true) or clockwise (false) from startAngle to endAngle.

• slices

  Type: Array.<Plain Object>.

  Array of plain objects to customize the appearance of each slice, where each object may have the following attributes to override the slice defaults:

  • offset

    Type: Number. Default: 0

    Slice offset as a fraction of the pie radius. If non-zero the slice is offset away from the center of the pie.

  • color

    Type: Color.

    Override the color from the colors array.

  • textInsideStyle

    Type: Plain Object.

    Text styling object overriding the default inner text style of the layer.

  • textOutsideStyle

    Type: Plain Object.

    Text styling object overriding the default outer text style of the layer.

  • strokeStyle

    Type: Plain Object.

    Stroke styling object overriding the slice border.

• sliceGradient

  Type: Number. Default: 1 (no gradient).

  Adds a luminosity gradient between the center side and border side of each slice.

  If positive, the luminosity at the center side is 100% and the luminosity at the border side is multiplied by sliceGradient.

  If negative, the luminosity at the center side is multiplied by sliceGradient and the luminosity at the border side is 100%.

• sliceVisibilityThreshold

  Type: Number. Default: 0.02.

  Size of the smallest possible slice, expressed as a fraction of the sum of all values in data. Values below the threshold are attributed to an additional "residue" slice at the end of the pie.

• startAngle

  Type: Number. Default: 0;

  Start angle of the pie in degrees clockwise from the vertical position.

• strokeStyle

  Type: Plain Object.

  Default stroke styling object for slices.

• textInside

  Type: String. Default: 'none'.

  Specifies the text to be used inside each slice, among the following choices: 'none' (no text), 'percentage' (slice size in percent), 'label' or 'value'.

• textInsideStyle

  Type: Plain Object.

  Text styling attributes overriding the inner slice text style.

• textOutside

  Type: String. Default: 'none'.

  Specifies the text to be used outside each slice, among the following choices: 'none' (no text), 'percentage' (slice size in percent), 'label' or 'value'.

• textOutsideStyle

  Type: Plain Object.

  Text styling attributes overriding the outer slice text style.

Examples

Pie chart

// draw a pie chart
$.Graph.pieChart( {
    data: [ 2.44, 1.18, 0.89, 0.70, 0.29, 0.27, 0.26 ],
    labels: [ 'Espresso', 'Cappuccino', 'Latte', 'Ristretto', 'Macchiato', 'Mocha', 'Americano' ],
    fontSize: 24,
    width: 1280,
    height: 720,
    fontWeight: 700,
    textInside: 'percentage',
    textInsideStyle: { color: 'white' },
    textOutside: 'label',
    borderSize: 3,
    legend: null
} ).addTo('svg');

Donut chart

// draw a donut chart
$.Graph.pieChart( {
    data: [ 2133, 58, 911, 838, 282, 56 ],
    labels: [ 'Coal', 'Oil', 'Gas', 'Nuclear', 'Hydro', 'Wind' ],
    width: 1280,
    height: 720,
    textInside: 'percentage',
    textInsideStyle: { color: 'white', fontSize: 24, fontWeight: 800 },
    textOutside: 'label',
    textOutsideStyle: { fontSize: 24, fontWeight: 800 },
    borderSize: 6,
    pieHole: 0.4,
    legend: null,
    sliceGradient: -0.8
} ).addTo('svg');

Semicircular donut chart with highlighted slice

// draw a semi-circular donut chart with highlighted slice
$.Graph.pieChart( {
    data: [ 2133, 58, 911, 838, 282, 56 ],
    labels: [ 'Coal', 'Oil', 'Gas', 'Nuclear', 'Hydro', 'Wind' ],
    width: 1280,
    height: 720,
    startAngle: -90,
    endAngle: 90,
    fontSize: 24,
    fontWeight: 700,
    textInside: 'percentage',
    textInsideStyle: { color: 'white' },
    textOutside: 'none',
    borderSize: 6,
    legend: { 
        position: { top: 20 }, 
        orientation: 'horizontal', 
        alignment: 'center' 
    },
    pieHole: 0.4,
    sliceGradient: 0.8,
    reverseCategories: false,
    chartArea: { top: 100, height: 900 },
    slices: [ {}, { offset: 0.075 } ]
} ).addTo('svg');