Skip to content

Latest commit

 

History

History
103 lines (75 loc) · 4.01 KB

APIs.md

File metadata and controls

103 lines (75 loc) · 4.01 KB
Raw

Constructors

The vegaTooltip module exports the following properties:

vegaTooltip

A convenience wrapper to initialize a tooltip handler and registering it with the view.

vegaTooltip.default(view [, options])

Parameter Type Description
view Vega View The visualization view.
options Options Options to customize the tooltip. See options for details.

Returns: The tooltip handler

Handler

A tooltip handler class. The constructor of this class takes only one argument options.

new vegaTooltip.Handler([options])

Parameter Type Description
options Options Options to customize the tooltip. See options for details.

When a tooltip is created, we automatically create a default stylesheet and attach it to the head. We also create a div element in the body that we the use for the tooltip.

The tooltip handler has the following methods.

Method Parameter(s) Description
call handler, event, item, value The tooltip handler function.

Unless you use the convenience method from above, you have to register the handler with the Vega view.

var tooltip = new vegaTooltip.Handler(options);

var runtime = vega.parse(spec);
var view = new vega.View(runtime)
  .initialize(document.getElementById("vis"))
  .tooltip(tooltip.call)
  .run();

Options

options can customize the tooltip. All of its properties are optional.

Property Type Description
offsetX Number The horizontal offset.
offsetY Number The vertical offset.
id String The ID of the tooltip element. The default name is vg-tooltip-element.
styleId String The ID of the stylesheet. The default name is vega-tooltip-style.
theme String A color theme.
Supported values: "light", "dark", or a custom name.
Default value: "light"
To customize your own theme, create CSS for the [THEME]-theme class.
disableDefaultStyle Boolean Disable the default style completely.
sanitize Function Function to convert value to string, and sanitize the HTML.
maxDepth Number The maximum recursion depth when printing objects in the tooltip.
formatTooltip Function Function to specify custom HTML inside tooltip element. It is highly recommended to sanitize any data from value before returning an HTML string.

The default values are:

var DEFAULT_OPTIONS =
{
  offsetX: 10,
  offsetY: 10,
  id: 'vg-tooltip-element',
  styleId: 'vega-tooltip-style',
  theme: 'light',
  disableDefaultStyle: false,
  sanitize: (value) => String(value).replace(/&/g, '&amp;').replace(/</g, '&lt;'),
  formatTooltip: vegaTooltip.formatValue
};

Sanitize

Vega Tooltip escapes HTML content from the Vega spec before displaying it in the tooltip. This prevents problems with users executing unknown code in their browser.

If you want to allow custom formatting, you may provide a custom sanitization function. For example, if you want to support Markdown, you could use simple-markdown.

function markdown(md) {
  var text  String(md);
  var parsed = SimpleMarkdown.defaultBlockParse(text);
  var html = SimpleMarkdown.defaultHtmlOutput(parsed);
  return vegaTooltip.escapeHTML(html);
}

var tooltip = new vegaTooltip.Handler({
  sanitize: markdown
});