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. As a result, the API methods of the Custom
Elements are all async (as they must await the wasm module instance).
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").
Ƭ PerspectiveViewerConfig: perspective.ViewConfig & { plugin?: string ; plugin_config?: any ; settings?: boolean }
rust/perspective-viewer/src/ts/viewer.ts:21
• default: Object
| Name | Type |
|---|---|
HTMLPerspectiveViewerElement |
typeof HTMLPerspectiveViewerElement |
HTMLPerspectiveViewerPluginElement |
typeof HTMLPerspectiveViewerPluginElement |
▸ convert(old, options?): Record<string, unknown> | ArrayBuffer | string
A migration utility for @finos/perspective-viewer and
@finos/perspective-workspace persisted state objects. If you have an
application which persists tokens returned by the .save() method of a
Perspective Custom Element, and you want to upgrade Perspective to the latest
version, this module is for you! You know who you are!
Say you have a <perspective-viewer> Custom Element from
@finos/perspective-viewer>=0.8.3, and have persisted an arbitrary persistence
token object:
const old_elem = document.querySelector("perspective-viewer");
const old_token = await old_elem.save();To migrate this token to the version of @finos/perspective-migrate itself:
import {convert} from "@finos/perspective-viewer`;
// ...
const new_elem = document.querySelector("perspective-viewer");
const new_token = convert(old_token);
await new_elem.restore(new_token);convert can also be imported in node for converting persisted tokens
outside the browser.
const {convert} = require("@finos/perspective-viewer/dist/cjs/migrate.js");| Name | Type | Description |
|---|---|---|
old |
string | ArrayBuffer | Record<string, unknown> |
the layout to convert, in <perspective-viewer> or <perspective-workspace> format. |
options |
PerspectiveConvertOptions |
a PerspectiveConvertOptions object specifying the convert options for this call. |
Record<string, unknown> | ArrayBuffer | string
a layout for either <perspective-viewer> or
<perspective-workspace>, updated to the perspective version of this
script's package.
rust/perspective-viewer/src/ts/migrate.ts:52
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↳
HTMLPerspectiveViewerElement
▸ getTable(wait_for_table?): Promise<Table>
Returns the perspective.Table() which was supplied to load()
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);| Name | Type | Description |
|---|---|---|
wait_for_table? |
boolean |
Whether to await load() if it has not yet been invoked, or fail immediately. |
Promise<Table>
A Promise which resolves to a perspective.Table
rust/perspective-viewer/src/ts/viewer.ts:188
▸ getView(): Promise<View>
Returns the underlying perspective.View currently configured for this
<perspective-viewer>. Because ownership of the perspective.View is
mainainted by the <perspective-viewer> it was created by, this View
may become deleted (invalidated by calling delete()) at any time -
specifically, it will be deleted whenever the PerspectiveViewConfig
changes. Because of this, when using this API, prefer calling
getView() repeatedly over caching the returned perspective.View,
especially in async contexts.
example Collapse grid to root
const viewer = document.querySelector("perspective-viewer");
const view = await viewer.getView();
await view.set_depth(0);Promise<View>
A Promise which ressolves to a perspective.View.
rust/perspective-viewer/src/ts/viewer.ts:212
▸ 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);| Name | Type |
|---|---|
table |
Table | Promise<Table> |
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:120
▸ unsafe_get_model(): Promise<number>
Get the raw pointer to this <perspective-viewer> WASM model, such that
it may be passed back to WASM function calls that take a
PerspectiveViewerElement as an argument.
Promise<number>
A pointer to this model
rust/perspective-viewer/src/ts/viewer.ts:541
▸ Static getExprtkCommands(): Promise<Record<string, string>[]>
Get metadata for ExprTK's supported commands.
Promise<Record<string, string>[]>
An array of JSON descriptors for ExprTK commands
rust/perspective-viewer/src/ts/viewer.ts:552
▸ resetThemes(themes): Promise<void>
Sets the theme names available via the <perspective-viewer> status bar
UI. Typically these will be auto-detected simply by including the
theme .css in a <link> tag; however, auto-detection can fail if
the <link> tag is not a same-origin request due to CORS. For servers
configured to allow cross-origin requests, you can use the
crossorigin attribute
to enable detection, e.g. <link crossorigin="anonymous" .. >. If for
whatever reason auto-detection still fails, you may set the themes via
this method. Note the theme .css must still be loaded in this case -
the resetThemes() method only lets the <perspective-viewer> know what
theme names are available.
example
const viewer = document.querySelector("perspective-viewer");
await viewer.resetThemes(["Material Light", "Material Dark"]);| Name | Type |
|---|---|
themes |
string[] |
Promise<void>
rust/perspective-viewer/src/ts/viewer.ts:418
▸ reset(all?): 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();| Name | Type | Default value | Description |
|---|---|---|---|
all |
boolean |
false |
Should expressions param be reset as well, defaults to |
Promise<void>
rust/perspective-viewer/src/ts/viewer.ts:331
▸ 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 currentView, i.e. the state it would be in afterload()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);| Name | Type | Description |
|---|---|---|
config |
string | PerspectiveViewerConfig | ArrayBuffer |
returned by save(). This can be any format returned by save(); the specific deserialization is chosen by typeof config. |
Promise<void>
A promise which resolves when the changes have been applied and rendered.
rust/perspective-viewer/src/ts/viewer.ts:255
▸ 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:282
▸ save(format): Promise<PerspectiveViewerConfig>
| Name | Type |
|---|---|
format |
"json" |
Promise<PerspectiveViewerConfig>
rust/perspective-viewer/src/ts/viewer.ts:283
▸ save(format): Promise<ArrayBuffer>
| Name | Type |
|---|---|
format |
"arraybuffer" |
Promise<ArrayBuffer>
rust/perspective-viewer/src/ts/viewer.ts:284
▸ save(format): Promise<string>
| Name | Type |
|---|---|
format |
"string" |
Promise<string>
rust/perspective-viewer/src/ts/viewer.ts:285
▸ 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:527
▸ 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.
| Name | Type | Description |
|---|---|---|
name? |
string |
Optionally a specific plugin name, defaulting to the current active plugin. |
Promise<HTMLElement>
The active or requested plugin instance.
rust/perspective-viewer/src/ts/viewer.ts:510
▸ 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");| Name | Type | Description |
|---|---|---|
name |
string |
The name of the custom element to register, as supplied to the customElements.define(name) method. |
Promise<void>
rust/perspective-viewer/src/ts/viewer.ts:92
▸ 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();
});| Name | Type | Description |
|---|---|---|
flat |
boolean |
Whether to use the element's current view config, or to use a default "flat" view. |
Promise<void>
rust/perspective-viewer/src/ts/viewer.ts:380
▸ download(flat): Promise<void>
Download this element's data as a CSV file.
| Name | Type | Description |
|---|---|---|
flat |
boolean |
Whether to use the element's current view config, or to use a default "flat" view. |
Promise<void>
rust/perspective-viewer/src/ts/viewer.ts:357
▸ 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();| Name | Type | Description |
|---|---|---|
force? |
boolean |
If supplied, explicitly set the config state to "open" (true) or "closed" (false). |
Promise<void>
rust/perspective-viewer/src/ts/viewer.ts:490
▸ 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:345
▸ 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({group_by: ["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:313
▸ 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:445
▸ notifyResize(force?): Promise<void>
Redraw this <perspective-viewer> and plugin when its dimensions or
visibility has been updated. By default, <perspective-viewer> will
auto-size when its own dimensions change, so this method need not be
called; when disabled via setAutoSize(false) however, this method
must be called, and will not respond to dimension or style changes to
its parent container otherwise. 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");
viewer.setAutoSize(false);
window.addEventListener("resize", () => viewer.notifyResize());| Name | Type | Default value | Description |
|---|---|---|---|
force |
boolean |
false |
Whether to re-render, even if the dimenions have not changed. When set to false and auto-size is enabled (the defaults), calling this method will automatically disable auto-size. |
Promise<void>
A Promise<void> which resolves when this resize event has
finished rendering.
rust/perspective-viewer/src/ts/viewer.ts:150
▸ 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:394
▸ setAutoSize(autosize?): Promise<void>
Determines the auto-size behavior. When true (the default), this
element will re-render itself whenever its own dimensions change,
utilizing a ResizeObserver; when false, you must explicitly call
notifyResize() when the element's dimensions have changed.
example Disable auto-size
await viewer.setAutoSize(false);| Name | Type | Default value | Description |
|---|---|---|---|
autosize |
boolean |
true |
Whether to re-render when this element's dimensions change. |
Promise<void>
rust/perspective-viewer/src/ts/viewer.ts:169
▸ 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);| Name | Type | Description |
|---|---|---|
value? |
number |
an optional throttle rate in milliseconds (integer). If not supplied, adaptive throttling is calculated from the average plugin render time. |
Promise<void>
rust/perspective-viewer/src/ts/viewer.ts:466
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
• 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>`;
}
| Name | Type |
|---|---|
view |
View |
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().
| Name | Type |
|---|---|
config |
any |
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);
}| Name | Type |
|---|---|
view |
View |
Promise<void>