Vars

Overview

Variables (vars) attach typed values to resources. Examples include the last update date, a processing status, or a chart's latest value. Plots, e-mails, grids, documents, views, jobs, and repos can have variables.

These vars can then later be referenced in comments, in descriptions and in document content with a simple reference {/u/novem_demo/p/stock_price/v/closing_price} (gives you the formatted closing price variable for @novem_demo's stock_price chart). E-mail content is the one place a reference is not resolved.

The API structure of vars looks as follows (using plots as an example):

stock_price                     => plot id
...
├── vars
│   ├── closing_price           => variable name
│   │   ├── about               => short description
│   │   ├── format              => numeric or date format
│   │   ├── type                => type of variable, relative, number, date, text
│   │   └── value               => value of variable
│   ├── dtd_return
│   │   ├── about
│   │   ├── format              => format of relative value
│   │   ├── type                => relative variable type
│   │   ├── threshold           => threshold visible when type is relative
│   │   └── value               => numeric relative value
│   └── ticker
│       ├── about
│       ├── type                => text type, shows only about and value
│       └── value               => text string
...

Using variables

To insert a variable, wrap the variable's FQNP in curly brackets. For example, to reference dtd_return you could write {/u/novem_demo/p/stock_price/v/dtd_return} and get something like ▲ +24.50%. The variables reference lists the surfaces where such a reference resolves.

Comments & Chats

Reference variables in messages and comment threads to include formatted values, such as a visitor count or the latest price.

Mails

E-mail content does not interpolate variables. A reference written in a mail body renders as literal text, so a live value has to be substituted before the content is posted.

Mail variables store metadata, readable over the API and through out.txt and out.ansi, and a mail's description interpolates like every other description.

Documents

Document content can include variables in metadata and in the text around embedded charts and tables.

Formatting variables

Set a variable's type and its formatting options to control its presentation. The output format and renderer also affect its appearance.

Text

The text variable is the simplest of the variables:

vars
└── ticker                  => variable id
    ├── about               => description
    ├── type                => text type
    └── value               => text string

It consists of just one control option, value, that will be embedded verbatim when used.

Date

Date variables accept a value and a date format. An embed can override the format.

vars
└── ticker                  => variable id
    ├── about               => description
    ├── type                => date type
    ├── format              => date format string
    └── value               => date value

Date input values are expected to be in YYYY-MM-DD format and the format endpoint supports the standard novem date formatting syntax.

Numeric

Similar to date, numeric is just a value with formatting instructions:

vars
└── ticker                  => variable id
    ├── about               => description
    ├── type                => numeric type
    ├── format              => number format string
    └── value               => numeric value

Any number is accepted with the format endpoint supporting the standard novem number formats.

Relative

A relative variable compares its value with a threshold:

vars
└── ticker                  => variable id
    ├── about               => description
    ├── type                => relative type
    ├── format              => format string
    ├── threshold           => threshold value
    └── value               => numeric value

Values below the threshold will be indicated as a negative relative value, usually with red colors and a downward arrow. Values above the threshold will be equally positive.