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"
}
}
},
...
}