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
    ├ haxis
    │   └ 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:

• One series representing the values to be displayed.
• The title of the tile.

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

• One series representing the values to be displayed.
• One haxis representing the horizontal axis.
• The title of the tile.

label tile

Created with show label. It contains no elements.

linechart tile

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

• One series for each time-series.
• The title of the title.
• The legend at the bottom of the tile.

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:

• One series describing the pie slices.
• The title of the title.
• The legend to the right of the tile.

plot tile

Created with show plot, or with a show scalar with a tensor or Z-function value. It contains the following sub-elements:

• One series for the Y-values of each data series.
• One haxis for the X-axis values.
• The title of the title.
• The legend at the bottom of the tile.

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:

• 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:

• One entry for each name-value pair.
• The title of the tile.

table tile

Created with show table. 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:

• A header cell at the top.
• A value for each data cell.

entry element

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

• name displays the name of the entry.
• value displays the name of the entry.

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:

• One value for each bound of the histogram (there are N+1 bounds for N buckets), or each X-value in the plot.

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:

• A value element for each value in the series. This element does not appear in histogram, which has custom formatting for its values.

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.

• 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:

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 the numbers on a given axis of a plot or linechart tile.
• All the numbers on a given series.
• All the numbers in a given value of a table.

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:

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

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:
  • The outputs of the number pipeline and date pipeline, and the name and header associated with those outputs, use right alignment.

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).

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.

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 header, the header cell.
• 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.

dateFormat property

Specifies the format to use to print out dates.

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.

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.

labelIcon property

Specifies the icon that should appear in the label tile.

minPrecision property

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

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

numbers property

Specifies the number rendering mode for the number pipeline.

precision property

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

seriesPattern property

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

Only applies if seriesType is line.

seriesType property

Specifies the display type of a series in a linechart.

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.

textColor property

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

thousandSeparator property

The thousands separator for the number pipeline.

tileColor property

Choose the accent color for a tile.

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.

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.

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.

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

tileW and tileH properties

Set the width (height) the tile.

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

unit property

Controls the unit of numbers in the number pipeline.

unitPosition property

Controls the position of the unit in the number pipeline.

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:

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