StyleCode reference
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 support tileX
, tileY
, tileW
, tileH
, tileBackground
and tilePlacement
.
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] │ ├ header │ └ value[?] └ title - upload
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:
- The
title
of the tile.
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:
- One
series
for each data series. The first series represents the X-axis values, the other series represent the Y-axis values. - The
title
of the title. - The
legend
at the bottom of the tile.
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:
value
contains the scalar value according to normal formatting rules.name
contains the title of the tile.
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:
- One
column
for each table column. It contains the cells, including those from the header and the totals line. - The
title
of the tile.
upload
tile
Created with show upload
. It contains the following sub-elements:
- The
title
of the tile.
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:
- A
value
element for each value in the series.
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
:
- All tiles with
tilePlacement: fixed
are placed on the grid at the position specified bytileX
,tileY
,tileW
andtileH
. If this would cause an overlap between two tiles, the tile that appears second in the source code is treated astilePlacement: bottom
instead. - 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.
- 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
andpercent
: likefixed
, but values are divided by 1000, 1000000 and 100 respectively, and use ak
,m
or%
suffix, respectively.scientific
: numbers are displayed in scientific formatX.FeY
whereY
is chosen so thatX
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⁻⁶and
10⁻⁹`), 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 the numbers on a given axis of a
plot
orlinechart
tile. - All the numbers on a given
series
. - All the numbers in a given
value
of atable
.
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 ofunit
, but only ifunitPosition
isleft
.[integer]
is the integer portion ofNumber / Scale
.[decimal-sep]
is the value offractionSeparator
. It only appears if the number of significant digitsD
is non-zero.[fraction]
is the fractional portion ofNumber / Scale
, rounded to the number of significant digitsD
.[suffix]
is the suffix determined along with the scale.[unit-right]
is the value ofunit
, but only ifunitPosition
isright
.
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
.
- For N series, an N-color gradient is created from the
tileColor
. If series i hascolor: gradient
it uses color i from this gradient. - 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
orjustify
, enforces the corresponding alignment. - If
default
, will use left alignment with a few exceptions:- The outputs of the number pipeline and date pipeline, and the
name
andheader
associated with those outputs, useright
alignment.
- The outputs of the number pipeline and date pipeline, and the
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 thetileColor
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:
- The name introduced by an
as
keyword (e.g."Qty"
fromOrders.Quantity as "Qty"
) - For a variable, the name without the table (e.g.
"Quantity"
fromOrders.Quantity
) - The text of the expression (e.g.
"sum(Orders.Quantity)"
fromsum(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:
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
.