Vars

Overview #

Novem is all about sharing live knowledge, and sometimes you want to share more than just the visual output itself. Think metadata such as when it was last updated or if there were any errors processing the data.

Perhaps there are things about the visual that you want to reference individually, such as what the latest closing or open price of your time-series chart was.

This is where novem variables, or vars as we call them, come into play. vars can be attached to any of the novem visuals (plots, grids, mails, docs), jobs or repos and provide additional information about the entity.

These vars can then later be referenced in comments or descriptions as well as in your mails and docs with a simple reference {/u/novem_demo/p/price_chart/closing_price} (gives you the formatted closing price variable for @novem_demo’s stock_price chart.

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

=> plot id
stock_price                     => plot id
...
├── vars
│   ├── closing_price           => variable name
│   │   ├── about               => short description
│   │   ├── format              => numeric or date format
│   │   ├── type                => type of variable, relative, numeber, 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 #

Using novem variables is fairly simple. In text fields that support simple novem markdown simply use the mustache or curly-brackets to wrap a FQNP to the variable id. For exmaple, to reference the above dtd_return you could write {/u/novem_demo/p/stock_price/v/dtd_return} and get the following ▲ +24.50%.

Comments & Chats #

One of the most common ways to use vars are in comments and chats. When discussion a technical subject it’s often helpful to reference hard data such as numbers of visitors or price performance inline in the conversation.

Novem variables let you reference live prices, performance measures or numbers directly in messages and comment threads.

Mails #

When building data-driven e-mails it’s nice to be able to refrence meta-variables such as recipient name or fund returns (if creating content for multiple funds). By moving these values into vars attached to the e-mail the templates can be clearner and better structured.

Pulling vars out of embedded charts also makes it possible to write rich content without having to independently source the chart data.

Documents #

Similarly to mails documents are also a common place to leverage vars both for document meta-information as well as for enriching content around embedded charts and data.

Formatting variables #

Novem variables offer a limited set of formatting instructions. Primarily the formatting job is left to the consumer of the variables so local styling considerations (such as output format and render type) can be taken into account.

We do however allow you to express certain meta-attributes about your vars to guide presentation. This is done by defining the type of the variable followed by relevant configuration options.

Text #

The text variable is the simples 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 verbatime when used.

Date #

Dates are slightly more complicated allowing the user to express formatting rules for the date. (The advantage here is that users can override date formatting on embed)

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 endpoints 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              => date format string
    └── value               => date value

Any number is accepted with the format endpoints supports the standard novem number formats.

Relative #

Relative is by far the most complicated of the vars. The idea with a relative variable is that it can show changes relative to a threshold.

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

The most important part here is threshold, 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.