Module for the <perspective-viewer> custom element. This module has no (real) exports, but importing it has a side effect: the PerspectiveViewerElementclass is registered as a custom element, after which it can be used as a standard DOM element.

Though <perspective-viewer> is written mostly in Rust, the nature of WebAssembly's compilation makes it a dynamic module; in order to guarantee that the Custom Elements extension methods are registered synchronously with this package's import, we need perform said registration within this wrapper module.

The documentation in this module defines the instance structure of a <perspective-viewer> DOM object instantiated typically, through HTML or any relevent DOM method e.g. document.createElement("perspective-viewer") or document.getElementsByTagName("perspective-viewer").

• PerspectiveViewerElement
• PerspectiveViewerPluginElement

• IPerspectiveViewerPlugin

• PerspectiveViewerConfig

Ƭ PerspectiveViewerConfig: perspective.ViewConfig & { plugin?: string ; plugin_config?: any ; settings?: boolean }

rust/perspective-viewer/src/ts/viewer.ts:16

The IPerspectiveViewerPlugin interface defines the necessary API for a <perspective-viewer> plugin, which also must be an HTMLElement via the Custom Elements API or otherwise. Rather than implement this API from scratch however, the simplest way is to inherit from <perspective-viewer-plugin>, which implements IPerspectiveViewerPlugin with non-offensive default implementations, where only the draw() and name() methods need be overridden to get started with a simple plugin.

Note that plugins are frozen once a <perspective-viewer> has been instantiated, so generally new plugin code must be executed at the module level (if packaged as a library), or during application init to ensure global availability of a plugin.

example

const BasePlugin = customElements.get("perspective-viewer-plugin");
class MyPlugin extends BasePlugin {
    get name() {
        return "My Plugin";
    }
    async draw(view) {
        const count = await view.num_rows();
        this.innerHTML = `View has ${count} rows`;
    }
}

customElements.define("my-plugin", MyPlugin);
const Viewer = customElements.get("perspective-viewer");
Viewer.registerPlugin("my-plugin");

• HTMLElement

  ↳ IPerspectiveViewerPlugin

• PerspectiveViewerPluginElement

• config_column_names
• min_config_columns
• name
• select_mode

• clear
• delete
• draw
• resize
• restore
• restyle
• save
• update

• get config_column_names(): string[]

The named column labels, if desired. Named columns behave differently in drag/drop mode than unnamed columns, having replace/swap behavior rather than insert. If provided, the length of config_column_names must be >= min_config_columns, as this is assumed by the drag/drop logic.

string[]

rust/perspective-viewer/src/ts/plugin.ts:80

• get min_config_columns(): number

The minimum number of columns required for this plugin to operate. This mostly affects drag/drop and column remove button behavior, preventing the use from applying configs which violate this min.

While this option can technically be undefined (as in the case of @finos/perspective-viewer-datagrid), doing so currently has nearly identical behavior to 1.

number

rust/perspective-viewer/src/ts/plugin.ts:71

• get name(): string

The name for this plugin, which is used as both it's unique key for use as a parameter for the plugin field of a ViewerConfig, and as the display name for this plugin in the <perspective-viewer> UI.

string

rust/perspective-viewer/src/ts/plugin.ts:52

• get select_mode(): "select" | "toggle"

Select mode determines how column add/remove buttons behave for this plugin. "select" mode exclusively selects the added column, removing other columns. "toggle" mode toggles the column on or off (dependent on column state), leaving existing columns alone.

"select" | "toggle"

rust/perspective-viewer/src/ts/plugin.ts:60

▸ clear(): Promise<void>

Clear this plugin, though it is up to the discretion of the plugin author to determine what this means. Defaults to resetting this element's innerHTML, so be sure to override if you want custom behavior.

example

async clear(): Promise<void> {
    this.innerHTML = "";
}

Promise<void>

rust/perspective-viewer/src/ts/plugin.ts:124

▸ delete(): Promise<void>

Free any resources acquired by this plugin and prepare to be deleted.

Promise<void>

rust/perspective-viewer/src/ts/plugin.ts:159

▸ draw(view): Promise<void>

Render this plugin using the provided View. While there is no provision to cancel a render in progress per se, calling a method on a View which has been deleted will throw an exception.

example

async draw(view: perspective.View): Promise<void> {
    const csv = await view.to_csv();
    this.innerHTML = `<pre>${csv}</pre>`;
}

Promise<void>

rust/perspective-viewer/src/ts/plugin.ts:95

▸ resize(): Promise<void>

Like update(), but for when the dimensions of the plugin have changed and the underlying data has not.

Promise<void>

rust/perspective-viewer/src/ts/plugin.ts:130

▸ restore(config): Promise<void>

Restore this plugin to a state previously returned by save().

Promise<void>

rust/perspective-viewer/src/ts/plugin.ts:154

▸ restyle(): Promise<void>

Notify the plugin that the style environment has changed. Useful for plugins which read CSS styles via window.getComputedStyle().

Promise<void>

rust/perspective-viewer/src/ts/plugin.ts:136

▸ save(): Promise<any>

Save this plugin's state to a JSON-serializable value. While this value can be anything, it should work reciprocally with restore() to return this plugin's renderer to the same state, though potentially with a different View.

save() should be used for user-persistent settings that are data-agnostic, so the user can have persistent view during refresh or reload. For example, @finos/perspective-viewer-d3fc uses plugin_config to remember the user-repositionable legend coordinates.

Promise<any>

rust/perspective-viewer/src/ts/plugin.ts:149

▸ update(view): Promise<void>

Draw under the assumption that the ViewConfig has not changed since the previous call to draw(), but the underlying data has. Defaults to dispatch to draw().

example

async update(view: perspective.View): Promise<void> {
    return this.draw(view);
}

Promise<void>

rust/perspective-viewer/src/ts/plugin.ts:109

The Custom Elements implementation for <perspective-viewer>, as well at its API. PerspectiveViewerElement should not be constructed directly (like its parent class HTMLElement); instead, use document.createElement() or declare your <perspective-viewer> element in HTML. Once instantiated, <perspective-viewer> works just like a standard HTMLElement, with a few extra perspective-specific methods.

example

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

example

document.body.innerHTML = `
    <perspective-viewer id="viewer"></perspective-viewer>
`;
const viewer = document.body.querySelector("#viewer");

• HTMLElement

  ↳ PerspectiveViewerElement

• getTable
• load

• reset
• restore
• save

• getAllPlugins
• getPlugin
• registerPlugin

• copy
• download
• toggleConfig

• delete
• flush
• getEditPort
• notifyResize
• restyleElement
• setThrottle

▸ getTable(): Promise<Table>

Returns the perspective.Table() which was supplied to load(). If load() has been called but the supplied Promise<perspective.Table> has not resolved, getTable() will await; if load() has not yet been called, an Error will be thrown.

example Share a Table

const viewers = document.querySelectorAll("perspective-viewer");
const [viewer1, viewer2] = Array.from(viewers);
const table = await viewer1.getTable();
await viewer2.load(table);

Promise<Table>

A Promise which resolves to a perspective.Table

rust/perspective-viewer/src/ts/viewer.ts:160

▸ load(table): Promise<void>

Load a perspective.Table. If load or update have already been called on this element, its internal perspective.Table will not be deleted, but it will bed de-referenced by this <perspective-viewer>.

example Load perspective.table

const my_viewer = document.getElementById('#my_viewer');
const tbl = perspective.table("x,y\n1,a\n2,b");
my_viewer.load(tbl);

example Load Promise<perspective.table>

const my_viewer = document.getElementById('#my_viewer');
const tbl = perspective.table("x,y\n1,a\n2,b");
my_viewer.load(tbl);

Promise<void>

A promise which resolves once the data is loaded, a perspective.View has been created, and the active plugin has rendered.

rust/perspective-viewer/src/ts/viewer.ts:115

▸ reset(): Promise<void>

Reset's this element's view state and attributes to default. Does not delete this element's perspective.table or otherwise modify the data state.

example

const viewer = document.querySelector("perspective-viewer");
await viewer.reset();

Promise<void>

rust/perspective-viewer/src/ts/viewer.ts:278

▸ restore(config): Promise<void>

Restore this element to a state as generated by a reciprocal call to save. In json (default) format, PerspectiveViewerConfig's fields have specific semantics:

• When a key is missing, this field is ignored; <perspective-viewer> will maintain whatever settings for this field is currently applied.
• When the key is supplied, but the value is undefined, the field is reset to its default value for this current View, i.e. the state it would be in after load() resolves.
• When the key is defined to a value, the value is applied for this field.

This behavior is convenient for explicitly controlling current vs desired UI state in a single request, but it does make it a bit inconvenient to use restore() to reset a <perspective-viewer> to default as you must do so explicitly for each key; for this case, use reset() instead of restore.

As noted in save(), this configuration state does not include the Table or its Schema. In order for restore() to work correctly, it must be called on a <perspective-viewer> that has a Table already load()-ed, with the same (or a type-compatible superset) Schema`. It does not need have the same rows, or even be populated.

example Restore a viewer from localStorage

const viewer = document.querySelector("perspective-viewer");
const token = localStorage.getItem("viewer_state");
await viewer.restore(token);

Promise<void>

A promise which resolves when the changes have been applied and rendered.

rust/perspective-viewer/src/ts/viewer.ts:203

▸ save(): Promise<PerspectiveViewerConfig>

Serialize this element's attribute/interaction state, but not the perspective.Table or its Schema. save() is designed to be used in conjunction with restore() to persist user settings and bookmarks, but the PerspectiveViewerConfig object returned in json format can also be written by hand quite easily, which is useful for authoring pre-conceived configs.

example Save a viewer to localStorage

const viewer = document.querySelector("perspective-viewer");
const token = await viewer.save("string");
localStorage.setItem("viewer_state", token);

Promise<PerspectiveViewerConfig>

a serialized element in the chosen format.

rust/perspective-viewer/src/ts/viewer.ts:230

▸ save(format): Promise<PerspectiveViewerConfig>

Promise<PerspectiveViewerConfig>

rust/perspective-viewer/src/ts/viewer.ts:231

▸ save(format): Promise<ArrayBuffer>

Promise<ArrayBuffer>

rust/perspective-viewer/src/ts/viewer.ts:232

▸ save(format): Promise<string>

Promise<string>

rust/perspective-viewer/src/ts/viewer.ts:233

▸ getAllPlugins(): Promise<HTMLElement[]>

Get all plugin custom element instances, in order of registration.

If no plugins have been registered (via registerPlugin()), calling getAllPlugins() will cause perspective-viewer-plugin to be registered as a side effect.

Promise<HTMLElement[]>

An Array of the plugin instances for this <perspective-viewer>.

rust/perspective-viewer/src/ts/viewer.ts:450

▸ getPlugin(name?): Promise<HTMLElement>

Get the currently active plugin custom element instance, or a specific named instance if requested. getPlugin(name) does not activate the plugin requested, so if this plugin is not active the returned HTMLElement will not have a parentElement.

If no plugins have been registered (via registerPlugin()), calling getPlugin() will cause perspective-viewer-plugin to be registered as a side effect.

Promise<HTMLElement>

The active or requested plugin instance.

rust/perspective-viewer/src/ts/viewer.ts:433

▸ Static registerPlugin(name): Promise<void>

Register a new plugin via its custom element name. This method is called automatically as a side effect of importing a plugin module, so this method should only typically be called by plugin authors.

example

customElements.get("perspective-viewer").registerPlugin("my-plugin");

Promise<void>

rust/perspective-viewer/src/ts/viewer.ts:87

▸ copy(flat): Promise<void>

Copies this element's view data (as a CSV) to the clipboard. This method must be called from an event handler, subject to the browser's restrictions on clipboard access. See https://www.w3.org/TR/clipboard-apis/#allow-read-clipboard.

example

const viewer = document.querySelector("perspective-viewer");
const button = document.querySelector("button");
button.addEventListener("click", async () => {
    await viewer.copy();
});

Promise<void>

rust/perspective-viewer/src/ts/viewer.ts:327

▸ download(flat): Promise<void>

Download this element's data as a CSV file.

Promise<void>

rust/perspective-viewer/src/ts/viewer.ts:304

▸ toggleConfig(force?): Promise<void>

Opens/closes the element's config menu, equivalent to clicking the settings button in the UI. This method is equivalent to viewer.restore({settings: force}) when force is present, but restore() cannot toggle as toggleConfig() can, you would need to first read the settings state from save() otherwise.

Calling toggleConfig() may be delayed if an async render is currently in process, and it may only partially render the UI if load() has not yet resolved.

example

await viewer.toggleConfig();

Promise<void>

rust/perspective-viewer/src/ts/viewer.ts:413

▸ delete(): Promise<void>

Deletes this element and clears it's internal state (but not its user state). This (or the underlying perspective.view's equivalent method) must be called in order for its memory to be reclaimed, as well as the reciprocal method on the perspective.table which this viewer is bound to.

Promise<void>

rust/perspective-viewer/src/ts/viewer.ts:292

▸ flush(): Promise<void>

Flush any pending modifications to this <perspective-viewer>. Since <perspective-viewer>'s API is almost entirely async, it may take some milliseconds before any method call such as restore() affects the rendered element. If you want to make sure any invoked method which affects the rendered has had its results rendered, call and await flush()

example Flush an unawaited restore()

const viewer = document.querySelector("perspective-viewer");
viewer.restore({row_pivots: ["State"]});
await viewer.flush();
console.log("Viewer has been rendered with a pivot!");

Promise<void>

A promise which resolves when the current pending state changes have been applied and rendered.

rust/perspective-viewer/src/ts/viewer.ts:261

▸ getEditPort(): Promise<number>

Gets the edit port, the port number for which Table updates from this <perspective-viewer> are generated. This port number will be present in the options object for a View.on_update() callback for any update which was originated by the <perspective-viewer>/user, which can be used to distinguish server-originated updates from user edits.

example

const viewer = document.querySelector("perspective-viewer");
const editport = await viewer.getEditPort();
const table = await viewer.getTable();
const view = await table.view();
view.on_update(obj => {
    if (obj.port_id = editport) {
        console.log("User edit detected");
    }
});

Promise<number>

A promise which resolves to the current edit port.

rust/perspective-viewer/src/ts/viewer.ts:368

▸ notifyResize(): Promise<void>

Redraw this <perspective-viewer> and plugin when its dimensions or visibility have been updated. This method must be called in these cases, and will not by default respond to dimension or style changes to its parent container. notifyResize() does not recalculate the current View, but all plugins will re-request the data window (which itself may be smaller or larger due to resize).

example Bind notfyResize() to browser dimensions

const viewer = document.querySelector("perspective-viewer");
window.addEventListener("resize", () => viewer.notifyResize());

Promise<void>

A Promise<void> which resolves when this resize event has finished rendering.

rust/perspective-viewer/src/ts/viewer.ts:139

▸ restyleElement(): Promise<void>

Restyles the elements and to pick up any style changes. While most of perspective styling is plain CSS and can be updated at any time, some CSS rules are read and cached, e.g. the series colors for @finos/perspective-viewer-d3fc which are read from CSS then reapplied as SVG and Canvas attributes.

Promise<void>

rust/perspective-viewer/src/ts/viewer.ts:341

▸ setThrottle(value?): Promise<void>

Determines the render throttling behavior. Can be an integer, for millisecond window to throttle render event; or, if undefined, will try to determine the optimal throttle time from this component's render framerate.

example Limit FPS to 1 frame per second

await viewer.setThrottle(1000);

Promise<void>

rust/perspective-viewer/src/ts/viewer.ts:389