Grid

Layout

A grid is defined by two plain-text files: layout, a box drawing of the dashboard, and mapping, which binds each box to a plot.

AI assisted, human approved — novem uses AI to review and keep our documentation up to date.

A grid has exactly two content files, both written as plain text (Content-Type: text/plain):

  • layout — the geometry: which panels exist and how big they are.
  • mapping — the content: which plot goes in each panel.

Writing either file re-parses both, so they can be updated independently and in any order. The parsed result is available as JSON under the grid's json/data.json (structure) and json/meta_data.json (mapping refs).

The layout is a rectangle drawn with three characters: +, - and |. Boxes are split into smaller boxes by divider lines, and each innermost box holds one instruction naming the plot label to show there:

+-------------+----------+
|             |          |
| {A:-}       |    {B:-} |
|             |          |
|             |          |
|             |          |
+-------------+----------+

The rules:

  • One outer frame. The whole drawing is one rectangle; blank rows and columns around it are ignored.
  • Dividers split a box in two (or more). A divider is a full row of -/+ (horizontal split) or a full column of |/+ (vertical split) running edge to edge inside a box. A divider can't mix - and |.
  • Splits nest. Each sub-box can be divided again, alternating directions as needed. Any rectangular arrangement is expressible.
  • Size is proportional. A box's share of the parent's width and height in characters becomes its share of the rendered dashboard. In the example above the left panel is 14 of 26 columns wide, so it gets roughly 55% of the width.
  • One instruction per box. Whatever remains in an innermost box after removing drawing characters and whitespace must be a single {LABEL} instruction.

{LABEL[:POSITION]}
  • LABEL — an alphanumeric label (A, B2, perf, …) defined in the mapping file. A label with no matching mapping line leaves the cell empty.
  • POSITION — an optional vertical anchor for the cell's content:
PositionMeaning
^top
-middle (default)
vbottom

{A}, {A:} and {A:-} are equivalent. Any other position character makes the instruction invalid and the cell renders empty.

The mapping file binds layout labels to plots, one binding per line:

LABEL => REFERENCE[,PARAM=VALUE]...

For example:

A => /u/novem_demo/p/nei_rgn_perf,c=f
B => /u/novem_demo/p/nei_rgn_tb,c=t,h=f
  • LABEL — the label used in the layout file.
  • REFERENCE — the FQNP of the plot to embed, e.g. /u/you/p/my_plot.
  • Parameters are comma-separated key=value pairs. Whitespace anywhere on the line is ignored, and lines without a => are skipped.

ParameterAliasValuesDefaultDescription
include_headerht, true, f, falsefalseInclude the plot's header in the cell
include_captionct, true, f, falsefalseInclude the plot's caption in the cell

An unrecognised value falls back to the parameter's default.

Note: if the same label appears on several mapping lines, the last line wins. Labels that exist in the mapping but not in the layout are simply unused.

After a successful write the parsed layout is exposed on the grid's JSON endpoints, useful for debugging a layout that doesn't split the way you expected:

curl -H "Authorization: Bearer $NOVEM_TOKEN" \
  https://api.novem.io/v1/vis/grids/my_dashboard/json/data.json

{
  "structure": {
    "type": "wrapper",
    "width": 26,
    "height": 7,
    "children": [
      {
        "type": "wrapper container",
        "width": 14.44,
        "height": 7,
        "children": [],
        "inst": { "lid": "NL--hwckacar", "position": "middle", "include_header": false, "include_caption": false }
      },
      {
        "type": "wrapper container",
        "width": 11.55,
        "height": 7,
        "children": [],
        "inst": { "lid": "NL--tguxadkh", "position": "middle", "include_header": false, "include_caption": true }
      }
    ]
  }
}

The lid values are internal link ids connecting each cell to its mapping entry. json/meta_data.json lists them alongside the labels.

  • Grid API — every grid endpoint.
  • API overview — verbs, permissions and the filesystem metaphor.
Next
API