JSignage:Graph:Styling attributes

This page is related to the jSignage Graph API.

Introduction

Almost all graphical details of chart and gauge drawing can be customized via the styling attributes / objects detailed below.

These attributes can be modified at different levels in the description of a graph, based on the principle of inheritance: those properties which are not defined on a style object at a lower level inherit the value of that property defined at a higher level. For instance the fontStyle of the title text can be set to 'italic', while the fontFamily property is inherited from that of its parent chart object.

General styling

All graph layers inherit the common attributes to jSignage layers (e.g., top, bottom, left, right, width, height, opacity, dur etc.), which can be used to style the graph layer itself.

The following attribute is specific to graph layers:

• chartArea

  Type: Plain Object. Default: null.

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

Text styling

All the text elements of a chart can be styled through the text styling attributes detailed below. These attributes can be used either directly within the graph layer (the highest level in the inheritance tree) or encapsulated within text styling objects to override general text styling at lower levels.

Text styling attributes

Text styling is controlled using the attributes below:

• color

  Type: Color. Default: 'black';

  The color used to fill the text.

• fontFamily

  Type: String. Default: 'Arial'.

  The font family or a list of font families in order of default. See the font-family CSS property for reference.

• fontSize

  Type: Number. Default: variable depending on the graph layer type.

  The font size in pixels.

• fontStyle

  Type: String. Default: 'normal'.

  Either 'italic' or 'normal'. See the font-style CSS property for reference.

• fontVariant

  Type: String. Default: 'normal'.

  Either 'smallcaps' or 'normal'. See the font-variant CSS property for reference.

• fontWeight

  Type: Number or String. Default: 'normal'.

  Numerical value between 0 and 1000 or, one of 'bold' (700) or 'normal' (400). See the font-weight CSS property for reference.

Text styling object

A text styling object is a plain object that contains one or more text styling attributes (detailed above).

Example

$.Graph.columnChart( {
    data: [ ... ], 
    width: 1280, height: 720,
    color: '#5b5',
    fontSize: 36,
    textInside: 'percentage',
    textInsideStyle: { 
        color: 'white', fontSize: 24, fontWeight: 800 
    },
    textOutside: 'value',
    textOutsideStyle: { 
        fontSize: 24, fontWeight: 'bold', fontFamily: 'Verdana' 
    },
    legend: {
        textStyle: { 
            color: '#ccc', fontSize: 18, fontWeight: 500 
        },
        position: 'right'
    }
} );

The text styling attributes are highlighted.

Stroke styling

Stroke styling is controlled with a stroke styling object.

Stroke styling object

A stroke styling object is a plain object that contains one or more of the following attributes:

• color

  Type: Color.

  The color used to stroke the line.

• lineCap

  Type: String.

  Either 'butt', 'round' or 'square'. See the stroke-linecap property for reference.

• lineDash

  Type: String or Array.<Number>.

  Either a string (one of the following: 'dots', 'squareDots', 'dashes', 'alternated') or an array of alternating dashes and gaps lengths in pixels. If the array is empty, dashing is disabled. If the array has an odd number of elements, it is repeated twice. See the stroke-dasharray property for reference.

• lineDashOffset

  Type: Number.

  Offset, positive or negative, into the dash pattern specified by lineDash applied at the start of the line. See the stroke-dashoffset property for reference.

• lineJoin

  Type: String.

  Either 'miter', 'round' or 'bevel'. See the stroke-linejoin property for reference.

• lineWidth

  Type: Number.

  The line width in pixels.

• miterLimit

  Type: Number.

  Maximum ratio of miter length to line width for miter joins. See the stroke-miterlimit property for reference.

Example of usage:

strokeStyle: { color: '#ccc', lineDash: 'dots', lineCap: 'round' },
axisStrokeStyle: { color: 'blue' }

Legend box styling

Legend box styling is controlled by assigning a legend styling object to the legend attribute.

Legend styling attribute

• legend

  Type: Plain Object.

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

Legend styling object

A legend styling object is a plain object that contains one or more of the following attributes:

• alignment

  Type: String.

  Alignment of the legend in its reserved space according to its orientation - use 'left', 'center' or 'right' for horizontal legends and, respectively, 'top', 'center' or 'bottom' for vertical ones.

• orientation

  Type: String. Default: 'horizontal' if the position attribute is 'top' or 'bottom', otherwise 'vertical'.

  Specifies the orientation of the legend - can be 'vertical' or 'horizontal'.

• position

  Type: String or Plain Object.

  Specifies the position of the legend box relative to the chart area itself. For automatic positioning on one side, use 'right', 'left', 'top', 'bottom' or 'in'. Otherwise, use an object with left, top, width and height properties to position the legend box inside the layer. Use 'none' to hide the legend.

• textStyle

  Type: Plain Object.

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

• strokeStyle

  Type: Plain Object.

  Stroke styling object overriding the default stroke style of the chart around the color patches in the legend.

• frameStyle

  Type: Plain Object. Default: null.

  Stroke styling object for the legend box frame or null for no frame around the legend box.

Example of usage:

legend: {
    position: { top: 20 },
    orientation: 'horizontal',
    alignment: 'center', 
    textStyle: { color: 'blue', fontSize: 18, fontWeight: 500 },
},

Axis styling

All of the graphs, except for the pie charts, display by default or can be configured to display, one or two axes using specific attributes like xAxis and yAxis for charts, respectively axis and altAxis for gauges, using some predefined settings, yet they are highly customizable. An axis is usually drawn as a line plus additional features at various positions along this line, such as text, tick marks and grid-lines (these positions are herein referred to as "ticks", independently of whether tick marks themselves are being drawn or not). Or it can be hidden altogether.

There are two types of axes:

• Continuous axis

  The continuous axis represents a range of continuous numerical values, with a minimum value, a maximum value and a baseline value. The labels are centered on the tick marks. The styling of a continuous axis is done through a continuous axis styling object.

• Discrete axis

  The discrete axis represents discrete categories, labeled independently, rather than values. The ticks marks separates the categories, the labels are thus centered between two tick marks. The styling of a discrete axis is done through a discrete axis styling object.

Axis styling attributes

The default styling of both types of axes can be set with the following attribute:

• axisStrokeStyle

  Type: Plain Object.

  Stroke styling object which serves as a default for drawing the axes.

For graphs allowing continuous axes, an additional attribute is available to be specified directly on the graph layer:

• locale

  Type: String. Default: null.

  Defines which locale is used for number formating; see the list of supported locale codes. If not provided, the global jSignage locale is used.

Gauge styling

Both linear gauges and circular gauges can be styled using the styling attributes and objects detailed on this page. Furthermore, there are two elements that are specific only to gauges: gauge indicator and gauge thresholds bar.

Marker styling

Line and area charts and scatter and bubble charts display data values using markers. These markers can be styled using the marker styling object.

Marker styling object

A marker styling object is a plain object that contains one or more of the following attributes:

• type

  Type: String. Default: 'none' (for line and area charts) or 'circle' (for scatter and bubble charts).

  Marker shape, one of 'none', 'circle', 'square', 'diamond', 'triangle' or 'star'.

• size

  Type: Number. Default: 2% of layer size.

  Marker size in pixels.

• color

  Type: Color.

  The fill color of the marker.

• strokeStyle

  Type: Plain Object. Default: 'circle'.

  The stroke style for the marker's outline.

Series styling

Line and area charts, as well as scatter and bubble charts, display input data as series of points, lines and / or areas, which can be styled using series styling attributes (directly within the chart layer). Some of these charts can display multiple series of data within the same chart and, in this case, each series can be individually styled using the same attributes, but encapsulated within series styling objects.

Series styling attributes

Series styling is controlled using the following attributes:

• color

  Type: Color. Default: The first color in the default color set ($.Graph.baseColors).

  The color to be used for markers and lines.

• fillColor

  Type: Color. Default: The value of the color attribute.

  The color to be used to fill the area(s) corresponding to series. It applies to area charts only.

• fillOpacity

  Type: Number. Default: 1.

  The opacity level to be used when filling the area(s) (for area charts) or the interior of the marker (for bubble charts) corresponding to series. The accepted values are between 0.0 (fully transparent) and 1.0 (fully opaque).

• fillOpacityGradient

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

  The opacity gradient level to be used when filling the area(s) corresponding to series. It applies to area charts only.

  If positive, the opacity level is ( fillOpacityGradient * fillOpacity ) at baseline and fillOpacity at chart's extremity.

  If negative, the opacity level is fillOpacity at baseline and ( - fillOpacityGradient * fillOpacity ) at chart's extremity.

• label

  Type: String. Default: '1'.

  The label of the series.

• line

  Type: String. Default: 'straight' (for line and area charts) or 'none' (for scatter charts).

  Line type between 'none', 'straight' or 'spline'. This doesn't apply to bubble charts.

• marker

  Type: Boolean or Plain Object. Default: A circle marker with a size chosen according to the chart area size.

  Either true (automatic marker), false (no marker) or a marker styling object.

• pointText

  Type: String.

  Selector for the text displayed next to data points. It can be one of the following:

  • 'none': no text
  • 'value': the point value
  • 'category': the category name associated to the point position along a discrete axis.
  • 'percentage' the point value in percents

• pointTextStyle

  Type: Plain Object.

  Text styling object to customize the text next to data points.

• strokeStyle

  Type: Plain Object. Default: solid line with a width chosen according to the chart area size.

  A stroke styling object for the connecting lines. This doesn't apply to bubble charts.

Series styling object

A series styling object is a plain object that contains one or more of the series styling attributes (detailed above).