JavaScript API

The JavaScipt API is currently quite minimal.

Embedding

See the getting started page.

Methods in the result object

The embed function returns a promise that resolves into an object that provides the current public API. The following methods are currently exposed:

# api.finalize()

Releases all resources and unregisters event listeners, etc.

# api.addEventListener(type, listener)

Adds an event listener, which is called when the user interacts with a mark instance. Currently, only "click" events are supported. The callback receives an event object as its first (and only) parameter. Its datum property contains the datum that the user interacted with.

# api.removeEventListener(type, listener)

Removes a registered event listener.

# api.getScaleResolutionByName(name)

Returns a named ScaleResolution object that allows for attaching event listeners and controlling the scale domain.

TODO: Complete documentation for ScaleResolution

Embed options

Custom tooltip handlers

GenomeSpy provides two built-in tooltip handlers.

The default handler displays the underlying datum's properties in a table. Property names starting with an underscore are omitted. The values are formatted nicely.

The refseqgene handler fetches a summary description for a gene symbol using the Entrez API. For an example, check the RefSeq gene track in this notebook.

Handlers are functions that receive the hovered mark's underlying datum and return a promise that resolves into a string, HTMLElement, or lit-html TemplateResult.

The function signature:

export type TooltipHandler = (
  datum: Record<string, any>,
  mark: Mark,
  /** Optional parameters from the view specification */
  params?: Record<string, any>
) => Promise<string | TemplateResult | HTMLElement>;

Use the tooltipHandlers option to register custom handlers or override the default. See the example below.

Examples

Overriding the default handler:

import { html } from "lit-html";

const options = {
  tooltipHandlers: {
    default: async (datum, mark, props) =>
      html`
        The datum has
        <strong>${Object.keys(datum).length}</strong> attributes!
      `,
  },
};

embed(container, spec, options);

To use a specific (custom) handler in a view specification:

{
  "mark": {
    "type": "point",
    "tooltip": {
      "handler": "myhandler",
      "params": {
        "custom": "param"
      }
    }
  },
  ...
}