Dashboard Metadata and Rendering

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 (e.g., replacing the old urth moniker.)

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
            "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.

The notebook can have one and only one layout associated with it indicated in the metadata.urth.dashboard.layout field. There are two defined layout types, report and grid, described in the sections below.

Report Layout

The report layout stacks cell outputs top-to-bottom, hiding cells that are marked as hidden. The height of each cell varies sizes to contain its content. The width of all cells is equivalent and set by the renderer.

To show a proper 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 grid layout positions cells in a grid of infinitely many rows and a fixed number of columns. The width and height of each cell is expressed in terms of these rows and columns. The physical height of each row is a fixed value while the width of each column is set by the renderer.

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 screen 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.