Stylesheets

With stylesheets, Chartbreaker can be highly customized. It is possible to change the layout, colors, fonts, and various other properties.

Stylesheets are basically JavaScript Arrays containing individual rules consisting of a selector, and a set of values to be applied to all objects matching the selector. In this regard, they are very similar to CSS. Different objects support different properties of different types. E.g. a property called "text-color" will accept any valid css color, while "line-width" will expect an integer, and "font" a CSS font descriptor.

A stylesheet could look like this:

const style = [
    {
        "selector": "chartset",
        "values": {
            "background-color": "#F7FBFF",
            // additional properties could follow here ...
        }
    },
    // additional rules could follow here ...
];

Selecting a Stylesheet

Every Controller can use its own stylesheet. It can be set at any time with the Controller.setStyle method. The method accepts three different kinds of parameters:

A stylesheet directly as an array
An alphanumeric style identifier (e.g. "foobar")
A URL pointing to a JSON file that is automatically loaded via AJAX

Style Identifiers

The style identifiers are resolved via the global setting "styleURL" (read or write via utils.get / utils.set).

import { utils } from '@stock3/charting-bundle-chartbreaker';
utils.set('styleURL', 'https://www.example.com/styles/');

controller.setStyle("foobar"); // => will try to load 'http://example.com/styles/foobar'

The advantage of using style identifiers is that they are serialized and deserialized automatically along with the contents of the chart. After deserializing a chart with an associated style identifier, the style is automatically loaded and applied. This makes it very easy, for example, to allow your users to switch between different themes.

In contrast, stylesheets that are applied directly or loaded via a URL are NOT serialized/deserialized and must be managed manually.

Selectors

Like in CSS, selectors are matched right to left, so it is not neccessary to always specify the complete object hierarchy. Also, multiple selectors may be concatenated with commas. E.g. to change the property of all markers, you could use "chart tool marker, chart marker" or just the selector "marker" instead.

For example, to change the line color of all tools, you could use:

{
    "selector": "tool",
    "values": {
        "line-color": "#f00"
    }
}

To change the line color of just TrendLines, you could use:

{
    "selector": "tool.TrendLine",
    "values": {
        "line-color": "#f00"
    }
}

You could provide a custom color for only the CCI indicator like this:

{
    "selector":"indicator.CCI layer.line",
    "values": {
        "line-color": "#00f"
    }
}

Rules are always applied in the order of appearance in the stylesheet. E.g. the following stylesheet will yield red lines for all TrendLines, but blue lines for all other tools:

{
    "selector": "tool",
    "values": {
        "line-color": "blue"
    }
},
{
    "selector": "tool.TrendLine",
    "values": {
        "line-color": "red" // this property will overwrite the previously encountered value for matching objects
    }
}

If the two blocks of the previous example were swapped, then ALL tools would be blue.

Objects

The following object hierarchy can be used for stylesheet selectors:

chartset: the chart set container
- chart: individual charts
  - plotarea: the plotarea inside of a chart, excluding axes
  - zoom: properties of the highlighted area displayed when zooming
  - measuring: the measuring band
  - handle: tool handles
  - crosshair: the crosshair cursor
    - marker: markers displayed on the x- and y-axis for the crosshair. Special ids: #time, #picker
  - grid: the horizontal and vertical grid lines
  - sessionBreaks: horizontal session break lines
  - legend: the legend box
    - button: buttons in the legend
  - yAxis: a y-axis
  - xAxis: a x-axis
  - tooltip: tooltips for buttons
  - button: utility buttons in the top left corner of each chart
  - loader: default loading indicator overlay
  - showMoreButton: the "show more" overflow button in the legend
  - watermark: the watermark drawn in the bottom-left of the plot area
  - timeseries: a timeseries (no direct style properties; visual appearance is controlled by the layer.<type> child selector)
    - layer: layers used to display a timeseries
      - flash: highlighting effect for data updates
  - indicator: an indicator (no direct style properties; visual appearance is controlled by the layer.<type> child selector)
    - layer: layers used to display an indicator
      - flash: highlighting effect for data updates
  - tool: tools
    - marker: markers used by tools
    - distance: helper lines used by some tools (e.g. trendlines)

Classes

Stylesheets also support classes, just like in CSS. Various classes are automatically applied to objects and can be used to make more specific rules:

Charts

isMain: the chart containing the main timeseries
isFirst: the first chart in a Controller
isLast: the last chart in a Controller
isBeforeMain: the chart immediately above the chart containing the main timeseries
isAfterMain: the chart immediately below the chart containing the main timeseries
hasLeftAxis: the chart has a visible left y-axis
hasRightAxis: the chart has a visible right y-axis
hasTopAxis: the chart has a visible top x-axis
hasBottomAxis: the chart has a visible bottom x-axis

Grid

isVertical: vertical lines
isHorizontal: horizontal lines

Y-Axes

isLeft: the axis is on the left
isRight: the axis is on the right
isPlaceholder: the axis is a placeholder (e.g. an additional representation of the primary axis on the opposite side)

X-Axes

isTop: the axis is on the top
isBottom: the axis is on the bottom

Indicators

Indicators are automatically assigned their type as a class. For example, the indicator "SMA" will have the class "SMA", so the following will match only layers used with this indicator type:

{
    "selector": "indicator.SMA layer",
    "values": {
        "line-color": "#f00"
    }
}

Tools

Just like Indicators, Tools are automatically assigned their type as a class. For example, the tool "TrendLine" will have the class "TrendLine", so following will only affect the color of TrendLines:

{
    "selector": "tool.TrendLine",
    "values": {
        "line-color": "#000"
    }
}

Reserved Selectors

The following selectors have special meaning and are not matched against the object hierarchy.

`palettes`

Palettes are sets of color definitions that can be used for example to populate color pickers with some predefined choices in the user interface. They are also used to automatically select line colors.

Chartbreaker contains defaults for all available palettes:

lines
stroke
fill
border

To define custom palettes:

{
    "selector" : "palettes",
    "values": {
        "lines" : [
            "#ffcf00", "#807b79", "#299dc3", "#696185",
            "#904583", "#658955", "#895555", "#9d9991"
        ]
    }
}

`variables`

Named variables that can be referenced in other style values using @variableName syntax. This lets you define a shared value once and reuse it across rules:

[
    { "selector": "variables", "values": { "brandColor": "#1E6EE6" } },
    { "selector": "tool.TrendLine", "values": { "line-color": "@brandColor" } },
    { "selector": "tool.HorizontalLine", "values": { "line-color": "@brandColor" } }
]

`textcolors`

Maps background color hex strings to a preferred foreground text color. Used internally when Chartbreaker needs to pick readable text for axis labels rendered on a colored background:

{ "selector": "textcolors", "values": { "#1E6EE6": "#ffffff" } }

Automatically Assigned Line Colors

If the stylesheet used does not specify fixed values for the line-color property of line layers (selector "layer.line"), this property is assigned automatically so that no color is used twice in a single chart. The colors are selected from the 'lines' palette.

Accessing Palettes via API

To access palettes programmatically via the API the following methods can be used:

controller.getStyle().getPalette('lines');

The value returned will be an array of strings, as defined in the stylesheet.

Property References

For a full reference of all style properties, defaults, and allowed values for each selector, see 4.1 Style Properties.md.