perspective-viewer

Module for the <perspective-viewer> custom element.

This module has no exports, but importing it has a side effect: the module:perspective_viewer~PerspectiveViewer class is registered as a custom element, after which it can be used as a standard DOM element.

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

• perspective-viewer
  • ~PerspectiveViewer ⇐ HTMLElement
    • new PerspectiveViewer()
    • .sort : [ 'array' ].<string>
    • .columns
    • .computed-columns
    • .aggregates
    • .filters : array
    • .plugin : string
    • .column-pivots : [ 'Array' ].<String>
    • .row-pivots : [ 'array' ].<string>
    • .editable : boolean
    • .throttle : integer | string
    • .worker
    • .table
    • .view
    • .load(data) ⇒ [ 'Promise' ].<void>
    • .update(data)
    • .notifyResize()
    • .clone(widget)
    • .delete(delete_table) ⇒ [ 'Promise' ].<boolean>
    • .restyleElement()
    • .save() ⇒ object
    • .restore(config) ⇒ [ 'Promise' ].<void>
    • .flush() ⇒ [ 'Promise' ].<void>
    • .clear()
    • .replace()
    • .reset()
    • .copy()
    • .toggleConfig()

---

perspective-viewer~PerspectiveViewer ⇐ HTMLElement

Kind: inner class of perspective-viewer
Extends: HTMLElement

• ~PerspectiveViewer ⇐ HTMLElement
  • new PerspectiveViewer()
  • .sort : [ 'array' ].<string>
  • .columns
  • .computed-columns
  • .aggregates
  • .filters : array
  • .plugin : string
  • .column-pivots : [ 'Array' ].<String>
  • .row-pivots : [ 'array' ].<string>
  • .editable : boolean
  • .throttle : integer | string
  • .worker
  • .table
  • .view
  • .load(data) ⇒ [ 'Promise' ].<void>
  • .update(data)
  • .notifyResize()
  • .clone(widget)
  • .delete(delete_table) ⇒ [ 'Promise' ].<boolean>
  • .restyleElement()
  • .save() ⇒ object
  • .restore(config) ⇒ [ 'Promise' ].<void>
  • .flush() ⇒ [ 'Promise' ].<void>
  • .clear()
  • .replace()
  • .reset()
  • .copy()
  • .toggleConfig()

---

new PerspectiveViewer()

The HTMLElement class for <perspective-viewer> custom element.

This class is not exported, so this constructor cannot be invoked in the typical manner; instead, instances of the class are created through the Custom Elements DOM API.

Properties of an instance of this class, such as module:perspective_viewer~PerspectiveViewer#columns, are reflected on the DOM element as Attributes, and should be accessed as such - e.g. instance.setAttribute("columns", JSON.stringify(["a", "b"])).

Example

// Create a new `<perspective-viewer>`
const elem = document.createElement("perspective-viewer");
elem.setAttribute("columns", JSON.stringify(["a", "b"]));
document.body.appendChild(elem);

---

perspectiveViewer.sort : [ 'array' ].<string>

Sets this perspective.table.view's sort property, an array of column names.

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update
Example (via Javascript DOM)

let elem = document.getElementById('my_viewer');
elem.setAttribute('sort', JSON.stringify([["x","desc"]));

Example (via HTML)

<perspective-viewer sort='[["x","desc"]]'></perspective-viewer>

---

perspectiveViewer.columns

The set of visible columns.

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update
Params

• columns array - An array of strings, the names of visible columns.

Example (via Javascript DOM)

let elem = document.getElementById('my_viewer');
elem.setAttribute('columns', JSON.stringify(["x", "y'"]));

Example (via HTML)

<perspective-viewer columns='["x", "y"]'></perspective-viewer>

---

perspectiveViewer.computed-columns

The set of visible columns.

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update
Params

• computed-columns array - An array of computed column objects

Example (via Javascript DOM)

let elem = document.getElementById('my_viewer');
elem.setAttribute('computed-columns', JSON.stringify([{name: "x+y", func: "add", inputs: ["x", "y"]}]));

Example (via HTML)

<perspective-viewer computed-columns="[{name:'x+y',func:'add',inputs:['x','y']}]""></perspective-viewer>

---

perspectiveViewer.aggregates

The set of column aggregate configurations.

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update
Params

• aggregates object - A dictionary whose keys are column names, and values are valid aggregations. The aggregates attribute works as an override; in lieu of a key for a column supplied by the developers, a default will be selected and reflected to the attribute based on the column's type. See perspective/src/js/defaults.js

Example (via Javascript DOM)

let elem = document.getElementById('my_viewer');
elem.setAttribute('aggregates', JSON.stringify({x: "distinct count"}));

Example (via HTML)

<perspective-viewer aggregates='{"x": "distinct count"}'>
</perspective-viewer>

---

perspectiveViewer.filters : array

The set of column filter configurations.

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update
Example (via Javascript DOM)

let filters = [
    ["x", "<", 3],
    ["y", "contains", "abc"]
];
let elem = document.getElementById('my_viewer');
elem.setAttribute('filters', JSON.stringify(filters));

Example (via HTML)

<perspective-viewer filters='[["x", "<", 3], ["y", "contains", "abc"]]'>
</perspective-viewer>

---

perspectiveViewer.plugin : string

Sets the currently selected plugin, via its name field.

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update

---

perspectiveViewer.column-pivots : [ 'Array' ].<String>

Sets this perspective.table.view's column_pivots property.

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update

---

perspectiveViewer.row-pivots : [ 'array' ].<string>

Sets this perspective.table.view's row_pivots property.

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update

---

perspectiveViewer.editable : boolean

Determines whether this viewer is editable or not (though it is ultimately up to the plugin as to whether editing is implemented).

Kind: instance property of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-config-update

---

perspectiveViewer.throttle : integer | string

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.

Kind: instance property of PerspectiveViewer
Example

<!-- Only draws at most 1 frame/sec. -->
<perspective-viewer throttle="1000"></perspective-viewer>

---

perspectiveViewer.worker

This element's perspective worker instance. This property is not reflected as an HTML attribute, and is readonly; it can be effectively set however by calling the load() method with a perspective.table` instance from the preferred worker.

Kind: instance property of PerspectiveViewer
Read only: true
Example

let elem = document.getElementById('my_viewer');
let table = elem.worker.table([{x:1, y:2}]);
elem.load(table);

---

perspectiveViewer.table

This element's perspective.table instance.

Kind: instance property of PerspectiveViewer
Read only: true

---

perspectiveViewer.view

This element's perspective.table.view instance. The instance itself will change after every PerspectiveViewer#perspective-config-update event.

Kind: instance property of PerspectiveViewer
Read only: true

---

perspectiveViewer.load(data) ⇒ [ 'Promise' ].<void>

Load data. If load or update have already been called on this element, its internal perspective.table will also be deleted.

Kind: instance method of PerspectiveViewer
Returns: [ 'Promise' ].<void> - A promise which resolves once the data is loaded and a perspective.view has been created.
Emits: module:perspective_viewer~PerspectiveViewer#perspective-click PerspectiveViewer#perspective-view-update ]);event:
Params

• data any - The data to load. Works with the same input types supported by perspective.table.

Example (Load CSV)

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

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 = async () => perspective.table("x,y\n1,a\n2,b");
my_viewer.load(tbl);

---

perspectiveViewer.update(data)

Updates this element's perspective.table with new data.

Kind: instance method of PerspectiveViewer
Emits: PerspectiveViewer#event:perspective-view-update
Params

• data any - The data to load. Works with the same input types supported by perspective.table.update.

Example

const my_viewer = document.getElementById('#my_viewer');
my_viewer.update([
    {x: 1, y: 'a'},
    {x: 2, y: 'b'}
]);

---

perspectiveViewer.notifyResize()

Determine whether to reflow the viewer and redraw.

Kind: instance method of PerspectiveViewer

---

perspectiveViewer.clone(widget)

Duplicate an existing <perspective-element>, including data and view settings. The underlying perspective.table will be shared between both elements

Kind: instance method of PerspectiveViewer
Params

• widget any - A <perspective-viewer> instance to clone.

---

perspectiveViewer.delete(delete_table) ⇒ [ 'Promise' ].<boolean>

Deletes this element's data and clears it's internal state (but not its user state). This (or the underlying perspective.table's equivalent method) must be called in order for its memory to be reclaimed.

Kind: instance method of PerspectiveViewer
Returns: [ 'Promise' ].<boolean> - Whether or not this call resulted in the underlying perspective.table actually being deleted.
Params

• delete_table boolean = true - Should a delete call also be made to the underlying table().

---

perspectiveViewer.restyleElement()

Restyles the elements and to pick up any style changes

Kind: instance method of PerspectiveViewer

---

perspectiveViewer.save() ⇒ object

Serialize this element's attribute/interaction state.

Kind: instance method of PerspectiveViewer
Returns: object - a serialized element.

---

perspectiveViewer.restore(config) ⇒ [ 'Promise' ].<void>

Restore this element to a state as generated by a reciprocal call to save or serialize.

Kind: instance method of PerspectiveViewer
Returns: [ 'Promise' ].<void> - A promise which resolves when the changes have been applied.
Params

• config object | string - returned by save or serialize.

---

perspectiveViewer.flush() ⇒ [ 'Promise' ].<void>

Flush any pending attribute modifications to this element.

Kind: instance method of PerspectiveViewer
Returns: [ 'Promise' ].<void> - A promise which resolves when the current attribute state has been applied.

---

perspectiveViewer.clear()

Clears the rows in the current table.

Kind: instance method of PerspectiveViewer

---

perspectiveViewer.replace()

Replaces all rows in the current table.

Kind: instance method of PerspectiveViewer

---

perspectiveViewer.reset()

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.

Kind: instance method of PerspectiveViewer

---

perspectiveViewer.copy()

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.

Kind: instance method of PerspectiveViewer

---

perspectiveViewer.toggleConfig()

Opens/closes the element's config menu.

Kind: instance method of PerspectiveViewer

---