Visualize.Hooks.Tooltip (Visualize v0.8.1)

Copy Markdown View Source

Phoenix LiveView hook that shows a datum's fields under the pointer (spec/10 §12).

TooltipHook needs no round trip: the server writes each datum's fields onto the element that draws it — Visualize.IR.Element.datum/2, or a mark's tooltip node (spec/14 §5.7) — and the hook reads them from the element under the pointer (D-75). A data-tooltip-template on the element or an ancestor formats the text with {field} placeholders; without one the tooltip lists field: value per line.

A click on a datum of a mark whose tooltip names an event pushes one wire event, visualize_event, with the element's key — its frame, its mark's position and its row's ordinal — the drawing's data-tooltip-drawn token, the pointer and the modifiers (spec/10 §12.3, D-170), to the component data-tooltip-target names, else to the LiveView. Visualize.Components.Chart and a board's cell are those components: they resolve the click to the row drawn and send the page a Visualize.Event.

In a sync group (spec/10 §4.3, §12.4) the hook publishes the pointer's x in domain units on the group's bus, and shows the datum element nearest to another member's hover.

Usage

<svg id="chart" phx-hook="TooltipHook">
  <g class="mark mark-circle" data-tooltip-template="{t}: {v}">
    <circle cx="10" cy="20" r="3" data-datum="t v" data-datum-t="1" data-datum-v="4"/>
  </g>
</svg>

A chart whose marks declare events is rendered through Visualize.Components.Chart, which mounts the hook itself.

Configuration

Data attributes on the hook element:

  • data-tooltip-class - class of the tooltip element the hook creates (default: "vis-tooltip")
  • data-tooltip-target - the phx-target a click's event goes to with pushEventTo; unset, it goes to the LiveView (D-161)
  • data-tooltip-drawn - the holder's token for the drawing on screen, sent with a click (D-170)
  • data-vis-hover - the palette's :hover, from attrs/1: the datum element shown is outlined in it (spec/10 §4.4); absent, nothing is outlined

Data attributes on the elements, written by the server (spec/10 §12.2):

  • data-datum - the field names, space-separated, in order
  • data-datum-<field> - the value of each field, _ in the name as -
  • data-named-<field> - the value's declared name, shown in place of the value (D-225)
  • data-tooltip-template - the text with {field} placeholders; the nearest wins
  • data-tooltip-event - the declared event a click delivers; absent, nothing is pushed
  • data-tooltip-show - "false": the element's mark takes clicks with nothing shown under the pointer, no tooltip and no outline (D-200)
  • data-frame, data-mark - on a mark's group with an event: its frame and position
  • data-row - on each datum element of such a mark: the row's ordinal in its rows

Summary

Functions

attrs(frame)

The hook element's data-vis-hover for a realized frame (spec/10 §12.1, §4.4): the palette's :hover as the frame's design and theme resolve it, in :literal mode, as a JSON object of SVG attributes the hook outlines the datum element it shows with.

items(tree)

The hit index of a drawing (spec/10 §12.5, D-197): the hook element's data-vis-items for a chart's generated element (Visualize.Chart.generate/2), as JSON. Every keyed datum element of a mark with an event — the elements a click on the SVG lands on — is its shape in the chart's user units, in drawing order, under its mark's event, frame and position, so a click on a canvas, which draws no element, sends the key the SVG would. Visualize.Components.Chart writes it on a canvas, with data-size.

js_hook()

Returns the JavaScript source of TooltipHook.

js_items()

Returns the JavaScript source of VisualizeItems, the hit index's reader (spec/10 §12.5), which the bundle defines before TooltipHook and does not export.

Functions

attrs(frame)

@spec attrs(Visualize.Chart.Frame.t()) :: %{required(String.t()) => String.t()}

The hook element's data-vis-hover for a realized frame (spec/10 §12.1, §4.4): the palette's :hover as the frame's design and theme resolve it, in :literal mode, as a JSON object of SVG attributes the hook outlines the datum element it shows with.

Examples

iex> chart = Visualize.Chart.from_map!(%{version: 2, frames: %{main: %{kind: :cartesian}}})
iex> frame = Visualize.Chart.Frame.new(chart, size: {100, 100})
iex> Visualize.Hooks.Tooltip.attrs(frame)
%{"data-vis-hover" => ~s({"stroke":"#333333","stroke-width":"2"})}

items(tree)

@spec items(Visualize.IR.Element.t()) :: String.t()

The hit index of a drawing (spec/10 §12.5, D-197): the hook element's data-vis-items for a chart's generated element (Visualize.Chart.generate/2), as JSON. Every keyed datum element of a mark with an event — the elements a click on the SVG lands on — is its shape in the chart's user units, in drawing order, under its mark's event, frame and position, so a click on a canvas, which draws no element, sends the key the SVG would. Visualize.Components.Chart writes it on a canvas, with data-size.

Examples

iex> design = %{version: 3, sources: %{s: %{fields: [:x, :y]}},
...>   frames: %{main: %{kind: :cartesian, margin: %{top: 0, right: 0, bottom: 0, left: 0},
...>     scales: %{x: %{kind: :linear, domain: [0, 10]}, y: %{kind: :linear, domain: [0, 10]}}}},
...>   marks: [%{type: :circle, data: :s, channels: %{x: :x, y: :y},
...>             options: %{radius: 4}, tooltip: %{event: :pick}}]}
iex> {:ok, applied} = Visualize.Chart.apply(design, sources: %{s: [%{x: 5, y: 5}]}, size: {100, 100})
iex> Visualize.Hooks.Tooltip.items(Visualize.Chart.generate(applied))
~s([{"event":"pick","context":null,"frame":"main","mark":0,"items":[[0,"c",50,50,4]]}])

js_hook()

Returns the JavaScript source of TooltipHook.

js_items()

Returns the JavaScript source of VisualizeItems, the hit index's reader (spec/10 §12.5), which the bundle defines before TooltipHook and does not export.