JSignage:Graph:Styling attributes

From SpinetiX Support Wiki

Jump to: navigation, search

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 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:

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:

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).

This page was last modified on 29 March 2018, at 13:52.