Frontfire documentation

DataColor

Version 2.1.0

No search results

Produce well readable data presentations!

What?

The DataColor class provides a colour palette for data visualisation. It contains 10 evenly distributed colour hues that allow a clear distinction in charts and tables. Each hue is available in 3 shades for foreground and 2 shades for background use. All colours are individually tuned for the light and dark theme, so when the user toggles dark theme, your charts remain readable and meaningful. (Try this page’s dark theme toggle with the preview below.)

globe Please excuse the wild spelling of the word “colour”. While source code is generally expected to use US English spelling for consistency with existing APIs, this documentation uses British/int’l English spelling which becomes especially apparent on this page.

Where?

As a modern JavaScript library, this code is compatible with the following environments:

Earlier versions may work for a limited feature set. The vastly outdated Internet Explorer is explicitly incompatible with this code. Should you be stuck in the past for whatever reason, a transpiler like Babel and a few polyfills might help you out.

This library is released under the terms of the MIT licence. See the complete licence text in the code repository for details.

Preview

Foreground
Text
Line
Normal
Light
Lighter
Gradients
Background
Light
Medium
Intense
Gradients

Hint: Hover a background swatch to apply the colour to the page background and see it in a larger area.

Documentation

This documentation lists all public members of the DataColor class. The available parameters are listed for each method, describing which of them are optional or alternative in which combination. The description explains the behaviour and parameter requirements. The return value is shown after the arrow.

A few examples further describe the usage and effect of a method.

Search

The members are categorised and can be searched (just type ahead). The search also uses aliases for many entries. Start the search text with an equals sign (=) to ignore aliases. Start the search text with the ^ sign to also only find names starting with the search term. Start the search text with the at sign (@) to search by source plugins. Press Escape to reset the search.

Constructor

DataColor

  • new DataColor() → DataColor

Creates a new DataColor instance. The constructor does nothing and the class has no state or instance methods. So don’t call the DataColor constructor.

Static methods

getColor

  • DataColor.getColor(colorId, type, darkTheme) → String

Gets the colour specified by its ID, type and theme. The return value has the CSS hsl() format.

The type specifies the point in the colour palette table:

  • f0: main foreground
  • f1: light foreground
  • f2: lighter foreground
  • b0: light background
  • b1: medium background
  • b2: intense background

New b1 type inserted in v2.1.0

getColorIds

  • DataColor.getColorIds() → Array (of String)

Gets the IDs of the colour palette. The IDs in bold font are the primary series and should be used exclusively if the number of primary entries is sufficient for the data to display. The primary colours are easier to distinguish from each other.

  • red
  • orange
  • yellow
  • olive
  • green
  • cyan
  • blue
  • darkblue
  • purple
  • pink

See also: DataColor.isPrimary()

getFreeColor

  • DataColor.getFreeColor(hue, type, darkTheme) → String

Gets a custom colour specified by its hue, type and theme. The hue can be used from the getFreeHue() function. This function can be used to generate a smooth gradient of the entire colour palette. The return value has the CSS hsl() format.

The type specifies the point in the colour palette table:

  • f0: main foreground
  • f1: light foreground
  • f2: lighter foreground
  • b0: light background
  • b1: medium background
  • b2: intense background

See also: DataColor.getFreeHue()

New b1 type inserted in v2.1.0

getFreeHue

  • DataColor.getFreeHue(x) → Number

Gets the hue of an interpolated colour from a range between 0 and 1. The return value can be used with the getFreeColor() function.

See also: DataColor.getFreeColor()

getName

  • DataColor.getName(colorId) → String
  • DataColor.getName(colorId, language) → String

Gets the localized name of a colour.

If no language is specified, the language is determined by the lang attribute of the document root element (<html>). Currently, the following languages are supported. Specifying a different language will return English names.

  • de: German
  • en: English

isPrimary

  • DataColor.isPrimary(colorId) → Boolean

Determines whether a colour is a primary colour.

parse

  • DataColor.parse(value, typePrefix) → Array

Parses a DataColor specification and returns an array containing [colorId, type]. A DataColor specification consists of a colorId and a numeric level (0 to 2), separated by a hyphen (-). The typePrefix must be set to "f" or "b" and will be included in the returned type, as it is not included in the DataColor specification. If unset, "f" is assumed. If the value is not a valid DataColor specification, null is returned.

Added in v2.1.0

parseGetColor

  • DataColor.parseGetColor(value, typePrefix, isDark) → String

Parses a DataColor specification and returns the color string if the value is valid; otherwise null. This is a combination of parse and getColor.

Added in v2.1.0