Kino.Output (Kino v0.4.0) View Source
A number of output formats supported by Livebook.
Link to this section Summary
Types
A control widget.
Animable output.
An empty output that should be ignored whenever encountered.
A raw image in the given format.
An input field.
Markdown content.
Livebook cell output may be one of these values and gets rendered accordingly.
Interactive data table.
Standalone text block.
Regular text, adjacent such outputs can be treated as a whole.
Interactive Vega-Lite graphic with data streaming capabilities.
Vega-Lite graphic.
Link to this section Types
Specs
control() :: {:control, attrs :: control_attrs()}
A control widget.
All controls have the following properties:
:type
- one of the recognised control types:ref
- a unique identifier:destination
- the process to send event messages to
On top of that, each control type may have additional attributes.
Events
All control events are sent to :destination
as {:event, id, info}
,
where info is a map including additional details. In particular, it
always includes :origin
, which is an opaque identifier of the client
that triggered the event.
Specs
control_attrs() :: %{ type: :keyboard, ref: control_ref(), destination: Process.dest(), events: [:keyup | :keydown | :status] } | %{ type: :button, ref: control_ref(), destination: Process.dest(), label: String.t() }
Specs
control_ref() :: reference()
Specs
frame_dynamic() :: {:frame_dynamic, pid()}
Animable output.
This output points to a server process that clients can talk to.
Communication protocol
A client process should connect to the server process by sending:
{:connect, pid()}
And expect the following reply:
{:connect_reply, %{output: Kino.Output.t() | nil}}
The server process may then keep sending one of the following events:
{:render, %{output: Kino.Output.t()}}
Specs
ignored() :: :ignored
An empty output that should be ignored whenever encountered.
Specs
A raw image in the given format.
Specs
input() :: {:input, attrs :: input_attrs()}
An input field.
All inputs have the following properties:
:type
- one of the recognised input types:ref
- a unique identifier:id
- a persistent input identifier, the same on every reevaluation:label
- an arbitrary text used as the input caption:default
- the initial input value:destination
- the process to send event messages to
On top of that, each input type may have additional attributes.
Specs
input_attrs() :: %{ type: :text, ref: input_ref(), id: input_id(), label: String.t(), default: String.t(), destination: Process.dest() } | %{ type: :textarea, ref: input_ref(), id: input_id(), label: String.t(), default: String.t(), destination: Process.dest() } | %{ type: :password, ref: input_ref(), id: input_id(), label: String.t(), default: String.t(), destination: Process.dest() } | %{ type: :number, ref: input_ref(), id: input_id(), label: String.t(), default: number() | nil, destination: Process.dest() } | %{ type: :url, ref: input_ref(), id: input_id(), label: String.t(), default: String.t() | nil, destination: Process.dest() } | %{ type: :select, ref: input_ref(), id: input_id(), label: String.t(), default: term(), destination: Process.dest(), options: [{value :: term(), label :: String.t()}] } | %{ type: :checkbox, ref: input_ref(), id: input_id(), label: String.t(), default: boolean(), destination: Process.dest() } | %{ type: :range, ref: input_ref(), id: input_id(), label: String.t(), default: number(), destination: Process.dest(), min: number(), max: number(), step: number() } | %{ type: :color, ref: input_ref(), id: input_id(), label: String.t(), default: String.t(), destination: Process.dest() }
Specs
input_id() :: String.t()
Specs
input_ref() :: reference()
Specs
markdown() :: {:markdown, binary()}
Markdown content.
Specs
t() :: ignored() | text_inline() | text_block() | markdown() | image() | vega_lite_static() | vega_lite_dynamic() | table_dynamic() | frame_dynamic() | input() | control()
Livebook cell output may be one of these values and gets rendered accordingly.
Specs
table_dynamic() :: {:table_dynamic, pid()}
Interactive data table.
This output points to a server process that serves data requests, handling filtering, sorting and slicing data as necessary.
Communication protocol
A client process should connect to the server process by sending:
{:connect, pid()}
And expect the following reply:
@type column :: %{
key: term(),
label: binary()
}
{:connect_reply, %{
name: binary(),
columns: list(column()),
features: list(:refetch | :pagination | :sorting)
}}
The client may then query for table rows by sending the following requests:
@type rows_spec :: %{
offset: non_neg_integer(),
limit: pos_integer(),
order_by: nil | term(),
order: :asc | :desc,
}
{:get_rows, pid(), rows_spec()}
To which the server responds with retrieved data:
@type row :: %{
# An identifier, opaque to the client
ref: term(),
# A string value for every column key
fields: list(%{term() => binary()})
}
{:rows, %{
rows: list(row()),
total_rows: non_neg_integer(),
# Possibly an updated columns specification
columns: :initial | list(column())
}}
Specs
text_block() :: {:text, binary()}
Standalone text block.
Specs
text_inline() :: binary()
Regular text, adjacent such outputs can be treated as a whole.
Specs
vega_lite_dynamic() :: {:vega_lite_dynamic, pid()}
Interactive Vega-Lite graphic with data streaming capabilities.
This output points to a server process that clients can talk to.
Communication protocol
A client process should connect to the server process by sending:
{:connect, pid()}
And expect the following reply:
{:connect_reply, %{spec: map()}}
The server process may then keep sending one of the following events:
{:push, %{data: list(), dataset: binary(), window: non_neg_integer()}}
Specs
vega_lite_static() :: {:vega_lite_static, spec :: map()}
Vega-Lite graphic.
spec
should be a valid Vega-Lite specification, essentially
JSON represented with Elixir data structures.
Link to this section Functions
Specs
control(control_attrs()) :: t()
See control/0
.
Specs
See frame_dynamic/0
.
Specs
See image/0
.
Specs
input(input_attrs()) :: t()
See input/0
.
Specs
Returns text_block/0
with the inspected term.
Specs
See markdown/0
.
Specs
See table_dynamic/0
.
Specs
See text_block/0
.
Specs
See text_inline/0
.
Specs
See vega_lite_dynamic/0
.
Specs
See vega_lite_static/0
.