Elements

Element types are used to filter rules so that they only apply to specific kinds of elements.

Tiles

Every element on the dashboard is contained within exactly one root element, which is always a tile.

All tiles (except logo) further support tileTitle and tileColor.

Most tiles contain data vectors defined in the with section of the Envision script. For tables, these are called columns. For summary tiles, they are called entries. For other tiles, they are called series.

General hierarchy of elements.

[N] indicates that the number of elements is specified statically in the Envision script, [?] that it is determined when the script is executed.

-  barchart
├ series
│   └ value[?]
└ title
- error
- form
└ title
- histogram
├ series
│   └ value[?]
└ title
- linechart
├ series[N]
│   └ value[?]
├ legend
└ title
- logo
- markdown
- piechart
├ series
│   └ value[?]
├ legend
└ title
- plot
├ series[N]
│   └ value[?]
└ title
- summary
├ entry[N]
│   ├ name
│   └ value
├ legend
└ title
- table
├ column[N]
│   └ value[?]
└ title


barchart tile

Created with show barchart. It contains the following sub-elements:

error tile

Generated by various show statements when placed in invalid conditions. It contains no elements.

form tile

Created with show form. It contains the following sub-elements:

histogram tile

Created with show histogram. It contains the following sub-elements:

label tile

Created with show label. It contains no elements.

linechart tile

Created with show linechart. It contains the following sub-elements:

logo tile

Created with show logo. It contains no elements.

markdown tile

Created with show markdown. It contains no elements.

piechart tile

Created with show piechart. It contains the following sub-elements:

plot tile

Created with show plot. It contains the following sub-elements:

scalar tile

Created with show table with exactly one line and column. As a name-value pair (like entry), it contains the following sub-elements:

summary tile

Created with show summary. It contains the following sub-elements:

table tile

Created with show table with more than one line or column. It contains the following sub-elements:

upload tile

Created with show upload. It contains the following sub-elements:

Other elements

column element

Represents a data vector in a table tile, and so supports the property as. It contains the following sub-elements:

entry element

A combination of a value and its name, it contains the following sub-elements:

For summary tiles, it corresponds to a data vector and so supports the as property.

header element

The topmost cell in a column, carries the name of the cell, follows the text pipeline.

legend element

In a linechart, plot, histogram or piechart, represents a section that displays associations between series and their colors or values.

name element

The name part of an entry, follows the text pipeline.

series element

Represents a data vector in a linechart, plot, barchart, piechart or histogram.

It supports the as property and follows the plot color pipeline. It has the following sub-elements:

title element

The title of a tile. Some tiles, such as scalar or logo, do not have a title element. Follows the text pipeline.

value element

A value in an entry, column or series. Follows the number pipeline (if a numeric value) or the date pipeline (for date values), as well as the text pipeline in all cases.

Pipelines

Rendering pipelines describe how dashboard data should be presented. The main purpose of StyleCode is to configure the various pipelines.

Dashboard Layout Pipeline

This pipeline computes the final position of each tile on the dashboard. Each tile is placed according to its tilePlacement:

1. All tiles with tilePlacement: fixed are placed on the grid at the position specified by tileX, tileY, tileW and tileH. If this would cause an overlap between two tiles, the tile that appears second in the source code is treated as tilePlacement: bottom instead.
2. The dashboard width is defined as the smallest width that can accommodate all tiles placed so far. If no tiles were placed so far, a dashboard width of 6 is assumed.
3. Starting on the row below the bottom-most tile, all tiles with tilePlacement: bottom are placed in the dashboard, filling each row left-to-right (up to the dashboard width) in the order in which they appear in the script, with dimensions 1×1.

Number Pipeline

This pipeline controls the pretty-printing of numbers. The main behaviour is determined by the numbers property.

• old: use the old rendering system to base the format on the “unit”. This option will be removed once the old rendering system will disappear.
• auto: collects all numbers within the same scope (a table column, a linechart series or axis, etc.) and picks a scale and precision. This is currently the default behaviour, unless overridden by the unit.
• simple: numbers are displayed as floating-point values with a certain number of trailing digits.
• thousands, millions and percent: like fixed, but values are divided by 1000, 1000000 and 100 respectively, and use a k, m or % suffix, respectively.
• scientific: numbers are displayed in scientific format X.FeY where Y is chosen so that X has exactly one digit.

Selecting the scale and suffix

The common point between auto, simple, thousands, millions, percent and scientific is that they choose a scale and a suffix according to this table:

Mode Scale Suffix
simple 1
thousands 1000 k
millions 1000000 m
percent 0.01 %
scientific The power of ten P = 10^N such that P <= x < 10 P 1eN
auto Complex, see below.

When numbers is auto, an algorithm examines a set of numbers and determines a scale among 10^9, 10^6, 10^3, 1, 10^-3, 10^-6 and 10^-9 (and associated prefixes b, m, k, ,10⁻³,10⁻⁶and10⁻⁹), and a precision, by trying to get the most visually appealing reasult when this scale, prefix and precision are applied to all numbers in the set.

The details of this optimization are implementation-defined (outside the scope of this specification) but the general idea is that the algorithm attempts to minimize noise digits (displaying 1 as 1.00 creates two digits of noise) as well as lost digits (displaying 1.23 as 1 loses two digits of data).

Each number on an Envision dashboard belongs to exactly one set of numbers, which will be considered together for the purpose of this optimization. These sets are:

All other numbers are considered alone.

Selecting the precision

The number will be displayed in format "X.Y", and the precision determines the number of digits in Y (a value between 0 and 16). This is a form of rounding, so 10.996 displayed with a precision of 2 becomes "11.00".

If numbers is auto, this precision has already been selected in the previous step.

The algorithm computes the number of significant digits D by looking for a sequence 000 or 999 in the decimal expansion of the number. For example:

Number D Ideal rendering
10 0 "10"
10.001 3 "10.001"
10.0001 0 "10"
10.399 3 "10.399"
10.3999 1 "10.4"

This number of significant digits D is then clamped between minPrecision and precision according to the following formula:

D = max(minPrecision, min(precision, D))


In other words: D should be between minPrecision and precision, and minPrecision wins.

Rendering the number

The rendering format is [unit-left][integer][decimal-sep][fraction][suffix][unit-right], where:

• [unit-left] is the value of unit, but only if unitPosition is left.
• [integer] is the integer portion of Number / Scale.
• [decimal-sep] is the value of fractionSeparator. It only appears if the number of significant digits D is non-zero.
• [fraction] is the fractional portion of Number / Scale, rounded to the number of significant digits D.
• [suffix] is the suffix determined along with the scale.
• [unit-right] is the value of unit, but only if unitPosition is right.

Digits in [integer] and [fraction] are combined in groups of three and separated by thousandSeparator.

Examples

Number numbers unit unitPosition precision minPrecision fractionSeparator thousandSeparator Result
1 auto " USD" auto auto 0 "." " " "1 USD"
0.249 percent "" auto auto 0 "." " " "24.9%"
0.249 scientific " m" auto auto 0 "," " " "2,49e-1 m"
1999 thousands "$" auto auto 0 "." " " "$2k"
1999 simple "$" right auto 2 "." "," "1,999.00$

Plot Color Pipeline

When plotting multiple series, each must receive its own recognizable color. This pipeline computes a color for each series, using the color.

1. For N series, an N-color gradient is created from the tileColor. If series i has color: gradient it uses color i from this gradient.
2. If the color property is a color, the corresponding series uses that color.

Text Pipeline

This pipeline controls the display of text. It is composed of independent sub-pipelines that control various aspects of the text.

Horizontal Text Aligment

Controlled by the textAlign property:

• If left, right, center or justify, enforces the corresponding alignment.
• If default, will use left alignment with a few exceptions:

Text alignment only applies to text positioned within a horizontal box wider than itself. Text in resizable boxes (such as the plot legends) or text attached to specific positions (axis labels, barchart labels) is not affected by horizontal alignment rules.

Text Color Pipeline

Controlled by the textColor property:

• If a color, the color is used for the text (the CSS property color is set to the corresponding color for the element).
• If default, the default color of the text is kept. For most text, this is a very dark grey set through CSS, but a few text elements instead use the tileColor to give a touch of color to a tile.

Text color applies to all text : this obviously includes table cell contents, but it also (perhaps more surprisingly) includes tile titles, axis labels, barchart values, and so on.

Properties

Properties can be assigned values. Each element inherits all the properties specified for its parent, which can then be overwritten by specifying different values for the element.

List of properties

as property

Specifies the name of a data vector (table columns, chart series, summary entries).

Applies to Type Default
column, series, entry (summary only) text See below

Although this can be specified with StyleCode syntax, the Envision script always provides values automatically, using, in decreasing order of priority:

1. The name introduced by an as keyword (e.g. "Qty" from Orders.Quantity as "Qty")
2. For a variable, the name without the table (e.g. "Quantity" from Orders.Quantity)
3. The text of the expression (e.g. "sum(Orders.Quantity)" from sum(Orders.Quantity))

cellBackground property

Specifies the background of a cell in a show table.

Applies to Type Default
In a column: header, value color, default default

By default, the background color of cells is white, and becomes #F8F8F8 when the table is zoomed in. This behaviour is retained when this property is default. Setting the property of a color uses that color for the background of the cells:

• For value, for all the value cells.

This property can, of course, be limited to only one column of a given table.

color property

Specifies the color of a series for the plot color pipeline.

Applies to Type Default
series color, gradient gradient

dateFormat property

Specifies the format to use to print out dates.

Applies to Type Default
values date-format, default default

The default value will be interpreted differently depending on the context. It usually is ddd MMM d, yyyy (e.g. “Mon Jan 1, 2001”) but will be instead MMM d, yyyy (e.g. “Jan 1, 2001”) in narrow contexts, such as a scalar tile of width 1.

fractionSeparator property

Specifies the separator between integer and fractional digits in the number pipeline.

Applies to Type Default
value text .

labelIcon property

Specifies the icon that should appear in the label tile.

Applies to Type Default
label icon, none none

minPrecision property

Specifies the minimum number of fractional digits to be displayed in the number pipeline.

Applies to Type Default
value Integer between 0 and 16 0

Overrides precision if greater, so {precision: 2, minPrecision: 3} actually uses {precision: 3}.

numbers property

Specifies the number rendering mode for the number pipeline.

Applies to Type Default
value old, auto, simple, thousands, millions, percent, scientific old

precision property

Specifies the maximum number of fractional digits to be displayed in the number pipeline.

Applies to Type Default
value Integer between 0 and 16 2

seriesPattern property

Specifies the pattern for displaying a line series in a linechart or plot.

Applies to Type Default
series in a linechart or plot solid, dotted, dashed solid

Only applies if seriesType is line.

seriesType property

Specifies the display type of a series in a linechart.

Applies to Type Default
series in a linechart line, stack line

The line value specifies that the series should be displayed as a line. Each value in the series is a vertex on the line, centered on the horizontal range corresponding to the date (day, week or month) for that value.

The stack value specifies that the series should be displayed as a bar. If multiple series are displayed with stack, their bars are stacked on top of each other. The horizontal dimensions of the bar are the horizontal range corresponding to the date for that value.

textAlign property

Specifies the horizontal text alignment in the text pipeline.

Applies to Type Default
value, name, header, title left, right, center, justify, default default

textColor property

Specifies the color of any text on the dashboard, for the text color pipeline.

Applies to Type Default
any color, default default

thousandSeparator property

The thousands separator for the number pipeline.

Applies to Type Default
value text U+00A0 (non-breaking space)

tileColor property

Choose the accent color for a tile.

Applies to Type Default
any tile color 000

Color pipelines use the accent color in their default mode to give a touch of color to the tile. For more information, refer to the color pipeline for each tile.

In practice, this property is rarely specified with StyleCode syntax. Instead, the standard Envision syntax specifies the tile color after the tile and position in the show xyz statement:

show table "Value" a1b1 tomato with ...

tilePlacement property

Choose the placement mode of a tile for the dashboard layout pipeline.

Applies to Type Default
any tile fixed, bottom bottom

In practice, this property is rarely specified with StyleCode syntax. Instead, the standard Envision syntax provides tile placement information after the title in the show xyz statement:

show table "Value" a1b1 with ...

If not provided, bottom is used. If provided, this property takes value fixed is used and the position token is used to assign properties tileX, tileY and optionally tileW and tileH (if provided).

tileTitle property

Set the title of the tile.

Applies to Type Default
any tile text ""

In practice, this property is rarely specified with StyleCode syntax. Instead, the standard Envision syntax places the title after the show xyz statement:

show table "\{missing} items not found" with ...

tileX and tileY properties

Set the horizontal (vertical) position of the left (top) side of the tile, relative to the left (top) side of the dashboard.

Applies to Type Default
any tile number 0

Part of the dashboard layout pipeline when tilePlacement is set to fixed.

tileW and tileH properties

Set the width (height) the tile.

Applies to Type Default
any tile number 1

Part of the dashboard layout pipeline when tilePlacement is set to fixed.

unit property

Controls the unit of numbers in the number pipeline.

Applies to Type Default
value text ""

unitPosition property

Controls the position of the unit in the number pipeline.

Applies to Type Default
value left, right, auto auto

The auto property is resolved based on the value of unit. It is right, except for the following units:

• €
• \$
• £

These units use left. Surrounding spaces are ignored when recognizing them. Other units may be added to this list.

Data types

Color type

A color can be specified using one of the following patterns:

• Hash-prefixed, three-digit hexadecimal (such as "#F00")
• Hash-prefixed, six-digit hexadecimal (such as "#FF0000")
• CSS color keywords (such as "red") from the full list of color keywords.

Date format type

A date format is text containing special sequences representing aspects of a date. Non-letter characters, such as , or white space, are printed out as-is. Letters are reserved, and should be escaped using backspace (\d prints an actual d).

The supported special sequences are given below for Monday January 1st, 2001:

Sequence Example Description
d 1 The day of the month.
dd 01 The day of the month, always two digits.
ddd Mon The day of the week, short three-letter name.
dddd Monday The day of the week, full name.
M 1 The month of the year.
MM 01 The month of the year, always two digits.
MMM Jan The month of the year, short three-letter name.
MMMM January The month of the year, full name.
y 1 The year within the century (but why would you use that ?)
yy 01 The two-digit year within the century, to plan for the year 2100 bug.
yyyy 2001 The four-digit year number.

For example, the format yyyy-MM-dd gives 2001-01-01, the format ddd MMM d, yyyy gives Mon Jan 1, 2001.