Skip to main content

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 BG.charts.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 BG.charts.utils.get / BG.charts.utils.set).

BG.charts.utils.set('styleURL', 'http://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
      • ** timeseries **: a timeseries (no properties)
        • ** layer **: layers used to display a timeseries.
          • ** flash**: highlighting effect for data updates
      • ** indicator **: an indicator (no properties)
        • ** 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

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 placeholder (e.g. just an additional representation of the primary axis on the opposite side)

Tools​

  • ** 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"
    }
}

Palettes​

In addition to the common rules, there is one reserved special selector: "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 using the reserved "palettes" selector:

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

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.