Visualisation

Available in: documents and e-mails.

{{ vis
  ref: /u/novem_demo/p/state_pop
  width: 100%
  align: left
  title: false
  caption: true
  include link: true
}}

Overview

The vis block embeds a live novem plot, grid or document in your content. It is a leaf block: do not add a {{ /vis }} tag.

Options

Options are written inside the double braces, inline or as YAML on several lines.

Reference

keyword: ref
options: shortname | local path | user path | official Novem URL

ref identifies the visualisation to embed and is the only required option.

All of these spellings use the same reference resolver:

• XVBzV — bare shortname
• /p/sales or p/sales — local path, with or without a leading slash
• /u/acme/p/sales or u/acme/p/sales — explicit user path
• https://novem.io/u/acme/p/sales — official Novem URL

The type segment may be p, g, m, or d for a plot, grid, mail, or document. Long local spellings such as /plots/sales are accepted too.

Shortname

The shortname is simply the shortname of the visualisation (available for all visualisations as a shortname endpoint), examples would be qNGgN or 2v1rV, referring to two public demo charts.

The public URL form https://novem.io/p/<shortname> resolves to that same shortname.

Local Path

Local paths resolve against the owner of the document or mail. Both compact forms (/p/state_pop, p/state_pop) and long forms (/plots/state_pop, plots/state_pop) are accepted.

Global Path

User paths let you refer to another user's visualisation by username and name.

This matches the existing API paths to view user visualisations under /u/<USERNAME>/<TYPE>/<ID>.

The leading slash is optional, and an official URL is equivalent. These three references therefore resolve identically:

/u/novem_demo/p/state_pop
u/novem_demo/p/state_pop
https://novem.io/u/novem_demo/p/state_pop

Alignment

keyword: align
options: left | right | center
default: center

Alignment positions the plot within the available space when it is narrower than the container.

Width

keyword: width
options: full | 1/2 | 0.5 | 80% | 240px
default: 100%

Width refers to the width of the plot relative to the current layout. If you have a two-column layout, a width of 100% fills a column.

Height

keyword: height
options: intrinsic | fill | 240px
default: intrinsic

intrinsic lets the visualisation take its natural height. fill gives it the rest of the page, or the whole of its grid area on a layout page, which is how a full-page chart or an embedded document page is written. Pixel heights are fixed.

In e-mails, the height alone sizes an embed: a pixel height up to 256px sets it, anything else gives 128px, and the width follows the plot's aspect ratio rather than the width option. The embed is centred in the column.

Bleed and area

keyword: bleed / area
options: bleed — top, right, bottom, left, x, y, all
options: area — a grid area name from the theme's layout for the page type

bleed runs the embed out to the named page edges, past the margins and the header and footer bands. area places it in a named area of a layout page.

Embedding a document

A document reference (/d/appendix or /u/acme/d/appendix) embeds that document's pages. Paired with height: fill on a page of its own, a page authored in one document appears inside another, with the outer document's theme and numbering:

{{ page autopaginate: false }}
{{ vis ref: /d/appendix_property, height: fill, title: false, caption: false }}

Include Title

keyword: title
options: true | false
default: true in documents, false in e-mails

Include the visualisation title if the visualisation has a title value set. E-mail embeds start without one, so an e-mail that wants the title has to ask for it with title: true.

Include Caption

keyword: caption
options: true | false
default: true

Includes the visualisation caption if the visualisation has one.

Include Link

keyword: include link
options: true | false
default: false

In e-mails, this option adds a link to the visualisation web page below the caption. This order also applies when the caption is overridden for the embed.

Override Title

keyword: title
options: "New title string"

This option allows you to override the title for the plot, the string replaces the resource metadata for this embed.

Override Caption

keyword: caption
options: "New caption string"

This option allows you to override the caption for the plot, the string replaces the resource metadata for this embed.

The caption sits 2px below the embedded visualisation. The gap is shared by documents and e-mails; see typography.

Examples

Embed a plot with full width

{{ vis
  ref: /u/novem_demo/p/nei_rgn_perf
  width: 100%
  title: false
  caption: true
}}

Inline syntax

{{ vis ref: /u/novem_demo/p/nei_rgn_tb, width: 80%, align: left }}

Side by side on a landscape page (documents)

{{ page
orient: landscape
cols: 2
}}

{{ vis
  ref: /u/novem_demo/p/nei_rgn_perf
  width: 100%
}}

{{ vis
  ref: /u/novem_demo/p/nei_rgn_hier
  width: 100%
}}