Dashboard Metadata and Rendering

DRAFT

This page documents:

1. The fields written to notebook documents (.ipynb files) by the jupyter-incubator/dashboards extension as of version 0.4.0
2. The interpretation of these fields used in jupyter-incubator/dashboards, jupyter-incubator/dashboards_bundlers, and jupyter-incubator/dashboards_server to render a notebook as a dashboard.

This format will almost certainly change ahead of the 1.0 release of the dashboard layout extension.

Notebook Fields

The following snippet of JSON shows the fields read and written by the dashboard projects. The more formal JSON Schema appears at the bottom of this post.

{
  "metadata": {
    "urth": {                             // original project codename
      "dashboard": {                      // dashboard tool metadata section
        "layout": "grid|report",          // algorithm to use for layout, grid if unspecified
        "cellMargin": <uint:10>,          // in grid layout, margin between cells in pixels
        "defaultCellHeight": <uint:20>,   // in grid layout, height in pixels of a logical row
        "maxColumns": <uint:12>           // in grid layout, total number of logical columns
      }
    }
  },
  "cells": [
    {
      "metadata": {
        "urth": {
          "dashboard": {
            "hidden": <bool:false>,       // if the cell output+widget area are visible in the layout
            "row": <uint:0>,              // in grid layout, logical row position
            "col": <uint:0>,              // in grid layout, logical column position
            "width": <uint:6>,            // in grid layout, logical width
            "height": <uint:2>            // in grid layout, logical height
          }
        }
      }
    }
  ]
}

Rendering

A dashboard renderer is responsible for reading the notebook document, executing cell inputs, and placing cell outputs in a dashboard layout. Cell outputs include anything that Jupyter Notebook 4.x renders in the cell output subarea or cell widget subarea in response to kernel messages or client-side events. A dashboard layout defines how cell outputs are positioned and sized with respect to one another.

There are two defined layout types, report and grid. The notebook can have one and only one layout associated with it indicated in the metadata.urth.dashboard.layout field. A renderer must read this field and then adhere to these constraints in order to render a conforming layout.

Report Layout

The renderer:

• Must execute cell inputs in the order defined by the notebook cells array.
• Must not render nor reserve space for cells that have urth.dashboard.hidden=true.
• Must arrange cell outputs top-to-bottom in order of execution (i.e., stacked vertically).
• Must space cell outputs vertically so that they do overlap at any time (e.g., a plot in the top-most cell should not overlap Markdown in the next down cell nor any cell below that).
• Should allow interactive widgets in cell outputs to render content that does overlap other cells (e.g., popups).
• Should wrap cell outputs that have variable length content (e.g., text) at a renderer determined width (e.g., browser width, responsive container element, fixed width).
• Should include a fixed amount of vertical whitespace between cell outputs.

Grid Layout

The renderer:

• Must execute cell inputs in the order defined by the notebook cells array.
• Must not render nor reserve space for cells that have urth.dashboard.hidden=true.
• Must define a logical grid with an unbounded number of rows and urth.dashboard.maxColumns columns per row.
• Must define a sreen viewport with infinite height and a renderer determined width (e.g., browser width, responsive container element, fixed width).
• Must map the grid origin (row zero, column zero) to the top left corner of the viewport.
• Must allocate urth.dashboard.defaultCellHeight pixels of space in the viewport to each grid row.
• Must allocate a fixed, renderer determined number of pixels in the viewport to each grid column.
• Must place a cell's outputs in the urth.dashboard.row and urth.dashboard.col slot in the grid.
• Must allocate urth.dashboard.width columns and urth.dashboard.height rows of space in the grid for a cell's output.
• Must separate each slot in the grid on the screen by urth.dashboard.cellMargin pixels.
• May clip, scale, wrap, or let overflow cell output that is bigger than its allocated space on the screen.