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.

dashboard
-  barchartseries
    │   └ value[?]
    └ title
- error
- formtitle
- histogramserieshaxis
    │   └ value[?]
    └ title
- linechartseries[N]
    │   └ value[?]
    ├ legendtitle
- logo
- markdown
- piechartseries
    │   └ value[?]
    ├ legendtitle
- plotseries[N]
    │   └ value[?]
    └ title
- summaryentry[N]  
    │   ├ name
    │   └ valuelegendtitle
- tablecolumn[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:

histogram tile

Created with show histogram, or with show scalar with a ranvar value. 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, or with a show scalar with a tensor or Z-function value. It contains the following sub-elements:

scalar tile

Created with show scalar, but depending on the type of the displayed value, a show scalar may also result in a plot or histogram instead. 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. 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.

haxis element

The horizontal axis in a histogram or plot. It contains the following sub-elements:

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 usually 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, haxis 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.

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:

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:

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:

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:

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

columnAppend and columnPrepend properties

Specifies whether a cell should be prepended at top of a column, or appended at the bottom of a column.

Applies to Type Default
column text or number ""

If any column in a table has a non-empty columnAppend, an additional line is appended at the bottom of the table (after the “lines/columns omitted” line, if any). All columns with a non-empty columnAppend will have the provided value appear on that line, formatted according to the StyleCode rules of the column.

If any column in a table has a non-empty columnPrepend, an additional line is prepended at the top of the table (right under the header cells). All columns with a non-empty columnPrepend will have the provided value appear on that line, formatted according to the StyleCode rules of the column.

columnReadOnly property

Specifies whether a column is read-only in an editable table. Has no effect on non-editable tables.

Applies to Type Default
column boolean false

columnWidth property

Specifies a multiplicative factor for the width of a column in a table. Applies both to editable and non-editable tables.

Applies to Type Default
column number 1

Weights must be ≥ 0. Each column occupy a fraction of the total width of the table equal to the ratio of its weight to the sum of all weights. By default, all weights are 1 and so the columns have equal widths.

For tables that are not zoomed in, a tile with width W displays a total of 2*W - 1 units of width, rounded up (so with W=2 the tile would display three width units: three columns with columnWidth=1, six columns with columnWidth=0.5 or two columns with columnWidth=2).

dashButton property

Specifies the label (and presence) of the dashboard’s “Start Run” button.

Applies to Type Default
dashboard text "Start run"

If set to an empty string, no button is displayed. This is usually done because a form tile in the dashboard has its own start button (set with formButton).

Note that even if set, other factors (such as the presence of slicing) may hide the button.

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.

formButton property

Specifies the existence and text of the “submit” button on a form tile.

Applies to Type Default
form text empty

If empty, no button is displayed on the form.

If provided, the button is displayed and the value of the property is used as the button’s label. Clicking the button submits the form. The syntax is: {formButton:"TextToDisplayOnButton"} as demonstrated in the following example:

show form "Dates" a2c3 {formButton:"Insert start and end dates"} with
 form.startdate as "Start date of your analysis"
 form.enddate as "End date of your analysis"

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, legend 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.

The legend value specifies that the series should not be displayed in the chart, only in the legend.

text property

Controls the display of text values.

Applies to Type Default
value, name, header, title text, link text

The text value specifies that the value should be displayed as-is.

The link value specifies that the value should be confirmed to be a http:// or https:// URL and displayed as a link. By default, the value is also used as the text of the link, but this can be overridden with property textLinkName.

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

textLinkName property

Controls the name of text values displayed as link.

Applies to Type Default
value, name, header, title text ""

If "", the URL of the link should be used as its name. Otherwise, the value of this property should be used as the name of the link. Only has an effect if text is link.

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:

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.