Create a new JavaScript Heap reference for this model instance.

Copy this viewer's View or Table data as CSV to the system clipboard.

Arguments

• method - The ExportMethod (serialized as a String) to use to render the data to the Clipboard.

JavaScript Examples

myDownloadButton.addEventListener("click", async () => {
    await viewer.copy();
})
Copy

Delete the internal [View] and all associated state, rendering this <perspective-viewer> unusable and freeing all associated resources. Does not delete the supplied [Table] (as this is constructed by the callee).

Calling any method on a <perspective-viewer> after [Self::delete] will throw.

JavaScript Examples

await viewer.delete();
Copy

Download this viewer's internal [View] data via a browser download event.

Arguments

• method - The ExportMethod to use to render the data to download.

JavaScript Examples

myDownloadButton.addEventListener("click", async () => {
    await viewer.download();
})
Copy

Restart this <perspective-viewer> to its initial state, before load().

Use Self::restart if you plan to call Self::load on this viewer again, or alternatively Self::delete if this viewer is no longer needed.

Exports this viewer's internal [View] as a JavaSript data, the exact type of which depends on the method but defaults to String in CSV format.

This method is only really useful for the "plugin" method, which will use the configured plugin's export (e.g. PNG for @perspective-dev/viewer-d3fc). Otherwise, prefer to call the equivalent method on the underlying [View] directly.

Arguments

• method - The ExportMethod to use to render the data to download.

JavaScript Examples

const data = await viewer.export("plugin");
Copy

Flush any pending modifications to this <perspective-viewer>. Since <perspective-viewer>'s API is almost entirely async, it may take some milliseconds before any user-initiated changes to the [View] affects the rendered element. If you want to make sure all pending actions have been rendered, call and await [Self::flush].

[Self::flush] will resolve immediately if there is no [Table] set.

JavaScript Examples

In this example, [Self::restore] is called without await, but the eventual render which results from this call can still be awaited by immediately awaiting [Self::flush] instead.

viewer.restore(config);
await viewer.flush();
Copy

Get an Array of all of the plugin custom elements registered for this element. This may not include plugins which called [registerPlugin] after the host has rendered for the first time.

Get the underlying [Client] for this viewer (as passed to, or associated with the [Table] passed to, [PerspectiveViewerElement::load]).

Arguments

• wait_for_client - whether to wait for [PerspectiveViewerElement::load] to be called, or fail immediately if [PerspectiveViewerElement::load] has not yet been called.

JavaScript Examples

const client = await viewer.getClient();
Copy

Get this viewer's edit port for the currently loaded [Table] (see [Table::update] for details on ports).

Gets a plugin Custom Element with the name field, or get the active plugin if no name is provided.

Arguments

• name - The name property of a perspective plugin Custom Element, or None for the active plugin's Custom Element.

Get render statistics. Some fields of the returned stats object are relative to the last time [PerspectiveViewerElement::getRenderStats] was called, ergo calling this method resets these fields.

JavaScript Examples

const {virtual_fps, actual_fps} = await viewer.getRenderStats();
Copy

Return a [perspective_js::JsViewWindow] for the currently selected region.

Get the underlying [Table] for this viewer (as passed to [PerspectiveViewerElement::load] or as the table field to [PerspectiveViewerElement::restore]).

Arguments

• wait_for_table - whether to wait for [PerspectiveViewerElement::load] to be called, or fail immediately if [PerspectiveViewerElement::load] has not yet been called.

JavaScript Examples

const table = await viewer.getTable();
Copy

Get the underlying [View] for this viewer.

Use this method to get promgrammatic access to the [View] as currently configured by the user, for e.g. serializing as an Apache Arrow before passing to another library.

The [View] returned by this method is owned by the [PerspectiveViewerElement] and may be invalidated by [View::delete] at any time. Plugins which rely on this [View] for their [HTMLPerspectiveViewerPluginElement::draw] implementations should treat this condition as a cancellation by silently aborting on "View already deleted" errors from method calls.

JavaScript Examples

const view = await viewer.getView();
Copy

Get a copy of the [ViewConfig] for the current [View]. This is non-blocking as it does not need to access the plugin (unlike [PerspectiveViewerElement::save]), and also makes no API calls to the server (unlike [PerspectiveViewerElement::getView] followed by [View::get_config])

Loads a [Client], or optionally [Table], or optionally a Javascript Promise which returns a [Client] or [Table], in this viewer.

Loading a [Client] does not render, but subsequent calls to [PerspectiveViewerElement::restore] will use this [Client] to look up the proviced table name field for the provided [ViewerConfigUpdate].

Loading a [Table] is equivalent to subsequently calling [Self::restore] with the table field set to [Table::get_name], and will render the UI in its default state when [Self::load] resolves. If you plan to call [Self::restore] anyway, prefer passing a [Client] argument to [Self::load] as it will conserve one render.

When [PerspectiveViewerElement::load] resolves, the first frame of the UI + visualization is guaranteed to have been drawn. Awaiting the result of this method in a try/catch block will capture any errors thrown during the loading process, or from the [Client] Promise itself.

[PerspectiveViewerElement::load] may also be called with a [Table], which is equivalent to:

await viewer.load(await table.get_client());
await viewer.restore({name: await table.get_name()})
Copy

If you plan to call [PerspectiveViewerElement::restore] immediately after [PerspectiveViewerElement::load] yourself, as is commonly done when loading and configuring a new <perspective-viewer>, you should use a [Client] as an argument and set the table field in the restore call as

A [Table] can be created using the @perspective-dev/client library from NPM (see [perspective_js] documentation for details).

JavaScript Examples

import perspective from "@perspective-dev/client";

const worker = await perspective.worker();
viewer.load(worker);
Copy

... or

const table = await worker.table(data, {name: "superstore"});
viewer.load(table);
Copy

Complete example:

const viewer = document.createElement("perspective-viewer");
const worker = await perspective.worker();

await worker.table("x\n1", {name: "table_one"});
await viewer.load(worker);
await viewer.restore({table: "table_one", columns: ["x"]});
Copy

... or, if you don't want to pass your own arguments to restore:

const viewer = document.createElement("perspective-viewer");
const worker = await perspective.worker();

const table = await worker.table("x\n1", {name: "table_one"});
await viewer.load(table);
Copy

Force open the settings for a particular column. Pass null to close the column settings panel. See [Self::toggleColumnSettings] for more.

Reset the viewer's ViewerConfig to the default.

Arguments

• reset_all - If set, will clear expressions and column settings as well.

JavaScript Examples

await viewer.reset();
Copy

If this element is in an errored state, this method will clear it and re-render. Calling this method is equivalent to clicking the error reset button in the UI.

Set the available theme names available in the status bar UI.

Calling [Self::resetThemes] may cause the current theme to switch, if e.g. the new theme set does not contain the current theme.

JavaScript Examples

Restrict <perspective-viewer> theme options to only default light and dark themes, regardless of what is auto-detected from the page's CSS:

viewer.resetThemes(["Pro Light", "Pro Dark"])
Copy

Recalculate the viewer's dimensions and redraw.

Use this method to tell <perspective-viewer> its dimensions have changed when auto-size mode has been disabled via [Self::setAutoSize]. [Self::resize] resolves when the resize-initiated redraw of this element has completed.

Arguments

• force - If [Self::resize] is called with false or without an argument, and auto-size mode is enabled via [Self::setAutoSize], [Self::resize] will log a warning and auto-disable auto-size mode.

JavaScript Examples

await viewer.resize(true)
Copy

Restores this element from a full/partial [perspective_js::JsViewConfig] (this element's user-configurable state, including the Table name).

One of the best ways to use [Self::restore] is by first configuring a <perspective-viewer> as you wish, then using either the Debug panel or "Copy" -> "config.json" from the toolbar menu to snapshot the [Self::restore] argument as JSON.

Arguments

• update - The config to restore to, as returned by [Self::save] in either "json", "string" or "arraybuffer" format.

JavaScript Examples

Loads a default plugin for the table named "superstore":

await viewer.restore({table: "superstore"});
Copy

Apply a group_by to the same viewer element, without modifying/resetting other fields - you can omit the table field, this has already been set once and is not modified:

await viewer.restore({group_by: ["State"]});
Copy

Restyle all plugins from current document.

JavaScript Examples

viewer.style = "--icon--color: red";
await viewer.restyleElement();
Copy

Save this element's user-configurable state to a serialized state object, one which can be restored via the [Self::restore] method.

JavaScript Examples

Get the current group_by setting:

const {group_by} = await viewer.restore();
Copy

Reset workflow attached to an external button myResetButton:

const token = await viewer.save();
myResetButton.addEventListener("clien", async () => {
    await viewer.restore(token);
});
Copy

Sets the auto-pause behavior of this component.

When true, this <perspective-viewer> will register an IntersectionObserver on itself and subsequently skip rendering whenever its viewport visibility changes. Auto-pause is enabled by default.

Arguments

• autopause Whether to enable auto-pause behavior or not.

JavaScript Examples

Disable auto-size behavior:

viewer.setAutoPause(false);
Copy

Sets the auto-size behavior of this component.

When true, this <perspective-viewer> will register a ResizeObserver on itself and call [Self::resize] whenever its own dimensions change. However, when embedded in a larger application context, you may want to call [Self::resize] manually to avoid over-rendering; in this case auto-sizing can be disabled via this method. Auto-size behavior is enabled by default.

Arguments

• autosize - Whether to enable auto-size behavior or not.

JavaScript Examples

Disable auto-size behavior:

viewer.setAutoSize(false);
Copy

Set the selection [perspective_js::JsViewWindow] for this element.

Determines the render throttling behavior. Can be an integer, for millisecond window to throttle render event; or, if None, adaptive throttling will be calculated from the measured render time of the last 5 frames.

Arguments

• throttle - The throttle rate in milliseconds (f64), or None for adaptive throttling.

JavaScript Examples

Only draws at most 1 frame/sec:

viewer.setThrottle(1000);
Copy

Asynchronously opens the column settings for a specific column. When finished, the <perspective-viewer> element will emit a "perspective-toggle-column-settings" CustomEvent. The event's details property has two fields: {open: bool, column_name?: string}. The CustomEvent is also fired whenever the user toggles the sidebar manually.

Toggle (or force) the config panel open/closed.

Arguments

• force - Force the state of the panel open or closed, or None to toggle.

JavaScript Examples

await viewer.toggleConfig();
Copy