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.

t()

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.

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

image() :: {:image, content :: binary(), mime_type :: binary()}

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

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

frame_dynamic(pid()) :: t()

See frame_dynamic/0.

Link to this function

image(content, mime_type)

View Source

Specs

image(binary(), binary()) :: t()

See image/0.

Specs

input(input_attrs()) :: t()

See input/0.

Specs

inspect(term()) :: t()

Returns text_block/0 with the inspected term.

Specs

markdown(binary()) :: t()

See markdown/0.

Specs

table_dynamic(pid()) :: t()

See table_dynamic/0.

Specs

text_block(binary()) :: t()

See text_block/0.

Specs

text_inline(binary()) :: t()

See text_inline/0.

Specs

vega_lite_dynamic(pid()) :: t()

See vega_lite_dynamic/0.

Specs

vega_lite_static(vega_lite_spec :: map()) :: t()

See vega_lite_static/0.