Skip to content
Reflex Reflex Reflex Docs

Dashboard

library

Builds the dashboard of a run: headers, paragraphs, lists, tables, dividers and charts that the server shows on the dashboard tab of the run. Every function appends one block after the previous ones and returns `Dashboard`, so calls can be chained. Blocks cannot be removed or reordered. The dashboard is stored as JSON when the run ends and `Dashboard.json` returns that same JSON. Text is given as a text table `{ value = "text", color = "red", background = "#eee", size = 14 }` in which only `value` is required. `color` and `background` are CSS colors and `size` is a font size in pixels. In lists and tables, give the items as a plain Lua list (`{ {value = "a"}, {value = "b"} }`): entries with a non-numeric key are rejected.

Functions

  • d self Adds a divider: a horizontal line, with the text in it when text is given.
  • h self Adds a header.
  • p self Adds a paragraph of text.
  • l self Adds a list.
  • t self Adds a table.
  • c self Adds one or more charts, drawn in the browser with Chart.js.
  • json string Returns the dashboard built so far as pretty-printed JSON, the same text that is stored when the run ends.

d()

Section titled “d()”
Dashboard.d()→selfDashboard.d(text: string)→selfDashboard.d(text: string, color: string)→selfDashboard.d(text: string, color: string, size: number)→self

Adds a divider: a horizontal line, with the text in it when text is given. Without text it is a plain line. Only the text color and the size (in pixels) can be set; there is no background.

Parameters

text string optional
Text shown in the divider; empty for a plain line
color string optional
Text color as a CSS color, like `red` or `#ff8800`
size number optional
Font size in pixels

Returns

self chainable The library itself, so calls can be chained.

Example runs in CI 

Dashboard.h({ value = "Nightly results" }).p({ value = "All checks passed" })
print(Dashboard.json())

h()

Section titled “h()”
Dashboard.h(text: DashboardTextOptions)→selfDashboard.h(text: DashboardTextOptions, size: number)→self

Adds a header. The text must be a text table, a plain string is rejected with `First parameter must be a text table`. The level is 1 (largest) to 6; a value below 1 becomes 1 and a value above 6 throws. The default is 1. The server shows levels 1 to 5 as `h1` to `h5`; level 6 is currently shown as level 1.

Parameters

text DashboardTextOptions
The header text
size number optional
Header level from 1 (largest) to 6

Returns

self chainable The library itself, so calls can be chained.

p()

Section titled “p()”
Dashboard.p(text: DashboardTextOptions)→self

Adds a paragraph of text. The text must be a text table; a plain string is rejected.

Parameters

text DashboardTextOptions
The paragraph text

Returns

self chainable The library itself, so calls can be chained.

l()

Section titled “l()”
Dashboard.l(value: table)→selfDashboard.l(value: table, ordered: boolean)→self

Adds a list. The items are text tables in a plain Lua list; entries with a non-numeric key throw. The second argument marks the list as ordered (`true`) or unordered (`false`, the default) and must be a boolean, otherwise the call throws. The server shows ordered lists with numbers and unordered lists with bullets.

Parameters

value table
List of text tables, one per item
ordered boolean optional
true for an ordered list, false for an unordered one

Returns

self chainable The library itself, so calls can be chained.

Example runs in CI 

Dashboard.l({ { value = "login works" }, { value = "checkout fails", color = "red" } })
print(Dashboard.json())

t()

Section titled “t()”
Dashboard.t(headers: table, values: table)→self

Adds a table. The header cells and every cell of every row are text tables. A row may have fewer cells than there are headers but not more (that throws `Cell size ... can't be bigger than headers size`); entries of `rows` that are not tables are skipped.

Parameters

headers table
List of text tables for the header cells
values table
List of rows; each row is a list of text tables, like `{ { {value = "a"}, {value = "b"} } }`

Returns

self chainable The library itself, so calls can be chained.

Example runs in CI 

Dashboard.t(
    { { value = "Check" }, { value = "Result" } },
    {
        { { value = "login" }, { value = "PASS", color = "green" } },
        { { value = "checkout" }, { value = "FAIL", color = "red" } },
    })
print(Dashboard.json())

c()

Section titled “c()”
Dashboard.c(charts: table)→self

Adds one or more charts, drawn in the browser with Chart.js. Pass a list of chart entries; each entry is a table with `height` and `width` (numbers; the server uses them as a percentage of the viewport height and width) and `chart`, a Chart.js configuration table with `type`, `data` and optionally `options`. The `chart` table is converted to JSON, so it can only hold strings, numbers, booleans and tables. Throws when the argument or an entry is not a table, when `height` or `width` is not a number, or when `chart` is not a table.

Parameters

charts table
List of chart entries `{ height, width, chart }`

Returns

self chainable The library itself, so calls can be chained.

Example runs in CI 

Dashboard.c({
    {
        height = 40,
        width = 30,
        chart = {
            type = "bar",
            data = {
                labels = { "passed", "failed" },
                datasets = { { label = "Checks", data = { 12, 3 } } },
            },
        },
    },
})
print(Dashboard.json())

json()

Section titled “json()”
Dashboard.json()→string

Returns the dashboard built so far as pretty-printed JSON, the same text that is stored when the run ends. It is an object whose keys are the block positions (`"0"`, `"1"`, ...) in call order; with no blocks it is an empty object.

Returns

string The dashboard as JSON text