Struct PerspectiveViewerElement 

pub struct PerspectiveViewerElement { /* private fields */ }

The <perspective-viewer> custom element.

JavaScript Examples

Create a new <perspective-viewer>:

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

Complete example including loading and restoring the Table:

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

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"});

Implementations

impl PerspectiveViewerElement

pub fn load(&self, table: JsValue) -> ApiResult<ApiFuture<()>>

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()})

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);

… or

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

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"]});

… 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);

pub fn delete(self) -> ApiFuture<()>

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.

Allowing a <perspective-viewer> to be garbage-collected without calling PerspectiveViewerElement::delete will leak WASM memory!

JavaScript Examples

await viewer.delete();

pub fn eject(&mut self) -> ApiFuture<()>

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.

pub fn getView(&self) -> ApiFuture<View>

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();

pub fn getViewConfig(&self) -> ApiFuture<JsViewConfig>

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)

pub fn getTable(&self, wait_for_table: Option<bool>) -> ApiFuture<Table>

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();

pub fn getClient(&self, wait_for_client: Option<bool>) -> ApiFuture<Client>

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();

pub fn getRenderStats(&self) -> ApiResult<JsValue>

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();

pub fn flush(&self) -> ApiFuture<()>

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();

pub fn restore(&self, update: JsValue) -> ApiFuture<()>

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"});

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"]});

pub fn resetError(&self) -> ApiFuture<()>

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.

pub fn save(&self) -> ApiFuture<JsValue>

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();

Reset workflow attached to an external button myResetButton:

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

pub fn download(&self, method: Option<JsString>) -> ApiFuture<()>

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();
})

pub fn export(&self, method: Option<JsString>) -> ApiFuture<JsValue>

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");

pub fn copy(&self, method: Option<JsString>) -> ApiFuture<()>

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();
})

pub fn reset(&self, reset_all: Option<bool>) -> ApiFuture<()>

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();

pub fn resize(&self, force: Option<bool>) -> ApiFuture<()>

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)

pub fn setAutoSize(&self, autosize: bool)

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);

pub fn setAutoPause(&self, autopause: bool)

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);

pub fn getSelection(&self) -> Option<JsViewWindow>

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

pub fn setSelection(&self, window: Option<JsViewWindow>) -> ApiResult<()>

Set the selection perspective_js::JsViewWindow for this element.

pub fn getEditPort(&self) -> Result<f64, JsValue>

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

pub fn restyleElement(&self) -> ApiFuture<JsValue>

Restyle all plugins from current document.

Self::restyleElement must be called for many runtime changes to CSS properties to be reflected in an already-rendered <perspective-viewer>.

JavaScript Examples

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

pub fn resetThemes(&self, themes: Option<Box<[JsValue]>>) -> ApiFuture<JsValue>

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"])

pub fn setThrottle(&self, val: Option<f64>)

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);

pub fn toggleConfig(&self, force: Option<bool>) -> ApiFuture<JsValue>

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();

pub fn getAllPlugins(&self) -> Array

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.

pub fn getPlugin( &self, name: Option<String>, ) -> ApiResult<JsPerspectiveViewerPlugin>

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.

pub fn toggleColumnSettings(&self, column_name: String) -> ApiFuture<()>

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.

pub fn openColumnSettings( &self, column_name: Option<String>, toggle: Option<bool>, ) -> ApiFuture<()>

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

Trait Implementations

impl Clone for PerspectiveViewerElement

fn clone(&self) -> PerspectiveViewerElement

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl CustomElementMetadata for PerspectiveViewerElement

const CUSTOM_ELEMENT_NAME: &'static str = "perspective-viewer"

The name of the element to register.

const STATICS: &'static [&'static str]

[optional] The names of the methods which should be static on the element.

const TYPE_NAME: &'static str = _

[optional] The name of the Rust struct.

fn struct_name() -> &'static str

[optional] A custom implementation of struct name to class name.

impl From<PerspectiveViewerElement> for JsValue

fn from(value: PerspectiveViewerElement) -> Self

Converts to this type from the input type.

impl FromWasmAbi for PerspectiveViewerElement

type Abi = u32

The Wasm ABI type that this converts from when coming back out from the ABI boundary.

unsafe fn from_abi(js: u32) -> Self

Recover a Self from Self::Abi.

impl IntoWasmAbi for PerspectiveViewerElement

type Abi = u32

The Wasm ABI type that this converts into when crossing the ABI boundary.

fn into_abi(self) -> u32

Convert self into Self::Abi so that it can be sent across the wasm ABI boundary.

impl LongRefFromWasmAbi for PerspectiveViewerElement

type Abi = u32

Same as RefFromWasmAbi::Abi

type Anchor = RcRef<PerspectiveViewerElement>

Same as RefFromWasmAbi::Anchor

unsafe fn long_ref_from_abi(js: Self::Abi) -> Self::Anchor

Same as RefFromWasmAbi::ref_from_abi

impl OptionFromWasmAbi for PerspectiveViewerElement

fn is_none(abi: &Self::Abi) -> bool

Tests whether the argument is a “none” instance. If so it will be deserialized as None, and otherwise it will be passed to FromWasmAbi.

impl OptionIntoWasmAbi for PerspectiveViewerElement

fn none() -> Self::Abi

Returns an ABI instance indicating “none”, which JS will interpret as the None branch of this option.

impl RefFromWasmAbi for PerspectiveViewerElement

type Abi = u32

The Wasm ABI type references to Self are recovered from.

type Anchor = RcRef<PerspectiveViewerElement>

The type that holds the reference to Self for the duration of the invocation of the function that has an &Self parameter. This is required to ensure that the lifetimes don’t persist beyond one function call, and so that they remain anonymous.

unsafe fn ref_from_abi(js: Self::Abi) -> Self::Anchor

Recover a Self::Anchor from Self::Abi.

impl RefMutFromWasmAbi for PerspectiveViewerElement

type Abi = u32

Same as RefFromWasmAbi::Abi

type Anchor = RcRefMut<PerspectiveViewerElement>

Same as RefFromWasmAbi::Anchor

unsafe fn ref_mut_from_abi(js: Self::Abi) -> Self::Anchor

Same as RefFromWasmAbi::ref_from_abi

impl TryFromJsValue for PerspectiveViewerElement

fn try_from_js_value(value: JsValue) -> Result<Self, JsValue>

Performs the conversion.

fn try_from_js_value_ref(value: &JsValue) -> Option<Self>

Performs the conversion.

impl VectorFromWasmAbi for PerspectiveViewerElement

type Abi = <Box<[JsValue]> as FromWasmAbi>::Abi

unsafe fn vector_from_abi(js: Self::Abi) -> Box<[PerspectiveViewerElement]>

impl VectorIntoWasmAbi for PerspectiveViewerElement

type Abi = <Box<[JsValue]> as IntoWasmAbi>::Abi

fn vector_into_abi(vector: Box<[PerspectiveViewerElement]>) -> Self::Abi

impl WasmDescribe for PerspectiveViewerElement

fn describe()

impl WasmDescribeVector for PerspectiveViewerElement

fn describe_vector()

impl SupportsConstructor for PerspectiveViewerElement

impl SupportsInstanceProperty for PerspectiveViewerElement

impl SupportsStaticProperty for PerspectiveViewerElement