Dashboard Metadata and Rendering

This page documents:

1. The fields written to notebook documents (.ipynb files) by the jupyter-incubator/dashboards extension
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.

The v0 spec is currently in use across the incubating dashboard projects. It evolved as the projects evolved and deserves revision based on lessons learned. We are drafting v1 of the spec in order to remove old monikers, make room for future improvements (e.g., aligning with a layout specification adopted by the community), and progress the incubating projects toward graduation.

Spec v1 (DRAFT)

Notebook Fields

{
  "metadata": {                             // notebook level metadata
    "extensions": {                         // per enhancement proposal
      "jupyter_dashboards" : {              // pypi package name
        "version": 1,                     // metadata format version
        "activeView": "<str:views key>",    // view to show when rendering if no picker is shown to the user
        "views": {
          "<str: tool defined ID 1>": {     // tool-assigned, unique layout ID
            "name": "<str>",                // user-assigned, unique human readable name
            "type": "grid",
            "cellMargin": <uint:10>,        // margin between cells in pixels
            "cellHeight": <uint:20>,        // height in pixels of a logical row
            "numColumns": <uint:12>         // total number of logical columns
          },
          "<str: tool defined ID 2>": {
            "name": "<str>",
            "type": "report"
          }
        }
      }
    }
  },
  "cells": [
    {
      "metadata": {
        "extensions": {
          "jupyter_dashboards": {
            "views": {
              "<str: tool defined ID 1>": {          // if present, means this cell has been processed
                "hidden": <bool:false>,              // if cell output+widget are visible in the layout
                "row": <uint:0>,                     // logical row position
                "col": <uint:0>,                     // logical column position
                "width": <uint:6>,                   // logical width
                "height": <uint:2>                   // logical height
              },
              "<str: tool defined ID 2>": {
                "hidden": <bool:false>               // if cell output+widget are visible in the layout
              }
            }
          }
        }
      }
    }
  ]
}

Rendering

TODO

Spec v0 (CURRENT)

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.