diff --git a/packages/perspective-viewer/README.md b/packages/perspective-viewer/README.md index 64eff415cc..21c9e3251d 100644 --- a/packages/perspective-viewer/README.md +++ b/packages/perspective-viewer/README.md @@ -3,26 +3,25 @@ ### Table of Contents - [registerPlugin][1] -- [\_attribute][2] -- [View][3] - - [view][4] - - [index][5] - - [message][6] - - [worker][7] - - [load][8] - - [update][9] - - [notifyResize][10] - - [copy][11] - - [delete][12] - - [save][13] - - [restore][14] - - [reset][15] -- [sort][16] -- [columns][17] -- [aggregates][18] -- [filters][19] -- [column-pivots][20] -- [row-pivots][21] +- [View][2] + - [sort][3] + - [columns][4] + - [aggregates][5] + - [filters][6] + - [view][7] + - [column-pivots][8] + - [index][9] + - [row-pivots][10] + - [message][11] + - [worker][12] + - [load][13] + - [update][14] + - [notifyResize][15] + - [copy][16] + - [delete][17] + - [save][18] + - [restore][19] + - [reset][20] ## registerPlugin @@ -30,30 +29,112 @@ Register a plugin with the component. **Parameters** -- `name` **[string][22]** The logical unique name of the plugin. This will be +- `name` **[string][21]** The logical unique name of the plugin. This will be used to set the component's `view` attribute. -- `plugin` **[object][23]** An object with this plugin's prototype. Valid keys are: +- `plugin` **[object][22]** An object with this plugin's prototype. Valid keys are: name : The display name for this plugin. create (required) : The creation function - may return a `Promise`. delete : The deletion function. mode : The selection mode - may be "toggle" or "select". -## \_attribute +## View + +**Extends ViewPrivate** + +HTMLElement class for ` +``` -A decorator for declaring a setter property of an HTMLElement descendent -class as serialized JSON. Handles converting these types before invoking -the underlying function/ +### columns + +The set of visible columns. **Parameters** -- `_default` **[object][23]** the default value to supply the setter when - undefined, removed or invalid. +- `columns` **[array][23]** An array of strings, the names of visible columns. -## View +**Examples** -**Extends ViewPrivate** +_via Javascript DOM_ -HTMLElement class for ` +``` + +### aggregates + +The set of column aggregate configurations. + +**Parameters** + +- `aggregates` **[object][22]** A dictionary whose keys are column names, and + values are valid aggregations. The `aggergates` 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][24] + +**Examples** + +_via Javascript DOM_ + +```javascript +let elem = document.getElementById('my_viewer'); +elem.setAttribute('aggregates', JSON.stringify({x: "distinct count"})); +``` + +_via HTML_ + +```javascript + +``` + +### filters + +The set of column filter configurations. + +**Examples** + +_via Javascript DOM_ + +```javascript +let filters = [ + ["x", "<", 3], + ["y", "contains", "abc"] +]; +let elem = document.getElementById('my_viewer'); +elem.setAttribute('filters', JSON.stringify(filters)); +``` + +_via HTML_ + +```javascript + +``` ### view @@ -63,6 +144,10 @@ Sets the currently selected plugin, via its `name` field. - `v` +### column-pivots + +Sets this `perspective.table.view`'s `column_pivots` property. + ### index The column name to index by. Due to the mutable nature of @@ -73,6 +158,10 @@ has been called. - `index` +### row-pivots + +Sets this `perspective.table.view`'s `row_pivots` property. + ### message When set, hide the data visualization and display the message. Setting @@ -81,7 +170,7 @@ render it hidden until the message is removed. **Parameters** -- `msg` **[string][22]** The message. This can be HTML - it is not sanitized. +- `msg` **[string][21]** The message. This can be HTML - it is not sanitized. **Examples** @@ -181,14 +270,14 @@ 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. -Returns **[Promise][24]<[boolean][25]>** Whether or not this call resulted in the +Returns **[Promise][25]<[boolean][26]>** Whether or not this call resulted in the underlying `perspective.table` actually being deleted. ### save Serialize this element's attribute/interaction state. -Returns **[object][23]** a serialized element. +Returns **[object][22]** a serialized element. ### restore @@ -197,7 +286,7 @@ Resotre this element to a state as generated by a reciprocal call to **Parameters** -- `x` **[object][23]** returned by `save`. +- `x` **[object][22]** returned by `save`. ### reset @@ -205,157 +294,54 @@ 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. -## sort - -Sets this `perspective.table.view`'s `sort` property, an array of column -names. - -**Examples** - -_via Javascript DOM_ - -```javascript -let elem = document.getElementById('my_viewer'); -elem.setAttribute('sort', JSON.stringify(["x"])); -``` - -_via HTML_ - -```javascript - -``` - -## columns - -The set of visible columns. - -**Parameters** - -- `columns` **[array][26]** An array of strings, the names of visible columns. - -**Examples** - -_via Javascript DOM_ - -```javascript -let elem = document.getElementById('my_viewer'); -elem.setAttribute('columns', JSON.stringify(["x", "y'"])); -``` - -_via HTML_ - -```javascript - -``` - -## aggregates - -The set of column aggregate configurations. - -**Parameters** - -- `aggregates` **[object][23]** A dictionary whose keys are column names, and - values are valid aggregations. The `aggergates` 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][27] - -**Examples** - -_via Javascript DOM_ - -```javascript -let elem = document.getElementById('my_viewer'); -elem.setAttribute('aggregates', JSON.stringify({x: "distinct count"})); -``` - -_via HTML_ - -```javascript - -``` - -## filters - -The set of column filter configurations. - -**Examples** - -_via Javascript DOM_ - -```javascript -let filters = [ - ["x", "<", 3], - ["y", "contains", "abc"] -]; -let elem = document.getElementById('my_viewer'); -elem.setAttribute('filters', JSON.stringify(filters)); -``` - -_via HTML_ - -```javascript - -``` - -## column-pivots - -Sets this `perspective.table.view`'s `column_pivots` property. - -## row-pivots - -Sets this `perspective.table.view`'s `row_pivots` property. - [1]: #registerplugin -[2]: #_attribute - -[3]: #view +[2]: #view -[4]: #view-1 +[3]: #sort -[5]: #index +[4]: #columns -[6]: #message +[5]: #aggregates -[7]: #worker +[6]: #filters -[8]: #load +[7]: #view-1 -[9]: #update +[8]: #column-pivots -[10]: #notifyresize +[9]: #index -[11]: #copy +[10]: #row-pivots -[12]: #delete +[11]: #message -[13]: #save +[12]: #worker -[14]: #restore +[13]: #load -[15]: #reset +[14]: #update -[16]: #sort +[15]: #notifyresize -[17]: #columns +[16]: #copy -[18]: #aggregates +[17]: #delete -[19]: #filters +[18]: #save -[20]: #column-pivots +[19]: #restore -[21]: #row-pivots +[20]: #reset -[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String +[21]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/String -[23]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object +[22]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Object -[24]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise +[23]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array -[25]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean +[24]: perspective/src/js/defaults.js -[26]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Array +[25]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Promise -[27]: perspective/src/js/defaults.js +[26]: https://developer.mozilla.org/docs/Web/JavaScript/Reference/Global_Objects/Boolean diff --git a/packages/perspective-viewer/src/js/view.js b/packages/perspective-viewer/src/js/view.js index ecd685bf4f..e4e4436c53 100644 --- a/packages/perspective-viewer/src/js/view.js +++ b/packages/perspective-viewer/src/js/view.js @@ -832,12 +832,11 @@ class View extends ViewPrivate { * names. * * @name sort + * @memberof View.prototype * @type {array} Array of column names - * * @example via Javascript DOM * let elem = document.getElementById('my_viewer'); * elem.setAttribute('sort', JSON.stringify(["x"])); - * * @example via HTML * */ @@ -862,12 +861,11 @@ class View extends ViewPrivate { * The set of visible columns. * * @name columns + * @memberof View.prototype * @param {array} columns 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 * */ @@ -882,16 +880,15 @@ class View extends ViewPrivate { * The set of column aggregate configurations. * * @name aggregates + * @memberof View.prototype * @param {object} aggregates A dictionary whose keys are column names, and * values are valid aggregations. The `aggergates` 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 {@link 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 * */ @@ -912,6 +909,7 @@ class View extends ViewPrivate { * The set of column filter configurations. * * @name filters + * @memberof View.prototype * @type {array} filters An arry of filter config objects. A filter * config object is an array of three elements: * * The column name. @@ -919,7 +917,6 @@ class View extends ViewPrivate { * {@link perspective/src/js/defaults.js} * * The filter argument, as a string, float or Array as the * filter operation demands. - * * @example via Javascript DOM * let filters = [ * ["x", "<", 3], @@ -927,7 +924,6 @@ class View extends ViewPrivate { * ]; * let elem = document.getElementById('my_viewer'); * elem.setAttribute('filters', JSON.stringify(filters)); - * * @example via HTML * */ @@ -975,6 +971,7 @@ class View extends ViewPrivate { * Sets this `perspective.table.view`'s `column_pivots` property. * * @name column-pivots + * @memberof View.prototype * @type {array} Array of column names */ @array_attribute @@ -1011,6 +1008,7 @@ class View extends ViewPrivate { * Sets this `perspective.table.view`'s `row_pivots` property. * * @name row-pivots + * @memberof View.prototype * @type {array} Array of column names */ @array_attribute @@ -1036,7 +1034,6 @@ class View extends ViewPrivate { * render it hidden until the message is removed. * * @param {string} msg The message. This can be HTML - it is not sanitized. - * * @example * let elem = document.getElementById('my_viewer'); * elem.setAttribute('message', '

Loading

'); @@ -1061,7 +1058,6 @@ class View extends ViewPrivate { * instance from the preferred worker. * * @readonly - * * @example * let elem = document.getElementById('my_viewer'); * let table = elem.worker.table([{x:1, y:2}]); @@ -1080,18 +1076,15 @@ class View extends ViewPrivate { * * @param {any} data The data to load. Works with the same input types * supported by `perspective.table`. - * * @example Load JSON * const my_viewer = document.getElementById('#my_viewer'); * my_viewer.load([ * {x: 1, y: 'a'}, * {x: 2, y: 'b'} * ]); - * * @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"); @@ -1123,7 +1116,6 @@ class View extends ViewPrivate { * * @param {any} data 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([