Name: vega-view
Owner: Vega
Description: View component and transforms for Vega visualizations.
Created: 2016-08-11 17:00:09.0
Updated: 2018-01-13 14:01:23.0
Pushed: 2018-01-18 05:07:53.0
Homepage: null
Size: 148
Language: JavaScript
GitHub Committers
| User | Most Recent Commit | # Commits |
|---|
Other Committers
| User | Most Recent Commit | # Commits |
|---|
View component for Vega visualizations. A View instantiates an underlying dataflow graph and provides a component for rendering and interacting with a visualization. When initialized with a container DOM element, the View adds a Canvas or SVG-based visualization to a web page. Alternatively, a View can be used either client-side or server-side to export static SVG or PNG (Canvas) images.
Methods for constructing and deconstructing views. In addition to the methods described below, View instances also inherit all (non-overidden) methods of the vega-dataflow Dataflow parent class.
# vega.View(runtime[, options]) <>
Constructor that creates a new View instance for the provided Vega dataflow runtime specification. If provided, the options argument should be an object with one or more of the following properties:
'canvas' or 'svg'). See the
renderer method.The View constructor call is typically followed by a chain of method calls to setup the desired view configuration. At the end of this chain, the run method evaluates the underlying dataflow graph to update and render the visualization.
view = new vega.View(runtime)
ogLevel(vega.Warn) // set view logging level
nitialize(document.querySelector('#view')) // set parent DOM element
enderer('svg') // set render type (defaults to 'canvas')
over() // enable hover event processing
un(); // update and render the view
Prepares the view to be removed from a web page. To prevent unwanted behaviors and memory leaks, this method removes any event listeners the visualization has registered on external DOM elements.
Methods for configuring the view state. These methods are often (but not always) invoked immediately after the View constructor, prior to the first invocation of the run method.
# view.initialize([container, bindContainer]) <>
Initializes internal rendering and event handling, then returns this view instance. If the DOM element container is provided, visualization elements (such as Canvas or SVG HTML elements) will be added to the web page under this containing element. If container is not provided, the view will operate in headless mode, and can still generate static visualization images using the image export methods. The optional DOM element (or unique CSS selector) bindContainer indicates the element that should contain any input elements bound to signals; if not specified the same container element as the visualization will be used.
Get or set the loader instance to use for data files and images. If the loader is updated after initialize has been invoked, the visualization will be reinitialized. If a Vega View loads data from an external URL, the load request is made immediately upon view construction. To ensure a custom loader is used, provide the loader as a constructor option! Invoking this method will update the loader only after initial data requests have been made.
Sets the current log level and returns this view instance. This method controls
which types of log messages are printed to the JavaScript console, and is
inherited from the
Dataflow
parent class. The valid level values are vega.None (the default),
vega.Warn, vega.Info, vega.Debug. See the
logger method in
vega-util for more.
Sets the renderer type (e.g., to 'canvas' (the default) or 'svg') and
returns this view instance. While typically invoked immediately upon view
creation, this method can be called at any time to change the renderer.
Additional renderer types may be used if registered via the renderModule method exported by vega-scenegraph; for an example see the vega-webgl-renderer.
# view.hover([hoverSet, updateSet]) <>
Enables hover event processing and returns this view instance. The optional
arguments specify which named encoding sets to invoke upon mouseover and
mouseout. The hoverSet defaults to 'hover', corresponding to the "hover"
set within a Vega mark specification "encode" block. The updateSet
defaults to 'update', corresponding to the "update" set within a Vega mark
specification "encode" block. If this method is never invoked, the view will
not automatically handle hover events. Instead, the underlying dataflow
definition will have to explicitly set up event streams for handling mouseover
and mouseout events.
Gets or sets the view background color. If no arguments are provided, returns the current background color. If color is specified, this method sets the background color and returns this view instance. This method does not force an immediate update to the view: invoke the run method when ready.
Gets or sets the view width, in pixels. If no arguments are provided, returns
the current width value. If width is specified, this method sets the width
and returns this view instance. This method does not force an immediate update
to the view: invoke the run method when ready. This method is
equivalent to view.signal('width'[, width]).
Gets or sets the view height, in pixels. If no arguments are provided, returns
the current height value. If height is specified, this method sets the
height and returns this view instance. This method does not force an immediate
update to the view: invoke the run method when ready. This method
is equivalent to view.signal('height'[, height]).
Gets or sets the view padding, in pixels. Padding objects take the form
{left: 5, top: 5, right: 5, bottom: 5}. If no arguments are provided, returns
the current padding value. If padding is specified, this method sets the
padding and returns this view instance. This method does not force an immediate
update to the view: invoke the run method when ready. This method
is equivalent to view.signal('padding'[, padding]).
Sets a flag indicating that layout auto-size calculations should be re-run
on the next pulse propagation cycle. If an autosize method of "pad" or
"fit" is being used, calling this method will cause the chart bounds layout
to be recomputed the next time the run method is invoked.
Methods for invoking dataflow evaluation and view rendering.
Evaluates the underlying dataflow graph and returns this view instance. The
optional encode argument is a String value indicating the name of a
custom "encode" set to run in addition to the standard "update" encoder.
If one or more data sets have been queued to be loaded from external files,
this method will function asynchronously: the method will initiate file loading
and return immediately, and the dataflow graph will be evaluated when file
loading completes. Any scenegraph elements modified during dataflow evaluation
will automatically be re-rendered in the view.
Internally, this method invokes the run method of the
Dataflow
parent class, and then additionally performs rendering.
Schedules a callback function to be invoked after the current dataflow evaluation completes. The callback function will be invoked with this view instance provided as the sole parameter. If dataflow evaluation is not currently occurring, the callback function is invoked immediately.
Renders the scenegraph and returns this view instance. If no arguments are provided, the entire scenegraph is redrawn. If provided, the update argument should be an array of “dirty” scenegraph items to redraw. Incremental rendering will be performed to redraw only damaged regions of the scenegraph.
During normal execution, this method is automatically invoked by the run method. However, clients may explicitly call this method to (re-)render the scene on demand (for example, to aid debugging).
Reports a “dirty” scenegraph item to be re-drawn the next time dataflow evaluation completes. This method is typically invoked by dataflow operators directly to populate a dirty list for incremental rendering.
Returns the DOM container element for this view, if it exists.
Returns the Vega scenegraph instance for this view.
Methods for accessing and updating dataflow signal values.
# view.signal(name[, value]) <>
Gets or sets a dataflow signal. If only the name argument is provided, returns the requested signal value. If value is also specified, updates the signal and returns this view instance. If the signal does not exist, an error will be raised. This method does not force an immediate update to the view: invoke the run method when ready.
Gets the state of signals and data sets in this view's backing dataflow graph. If no arguments are specified, returns an object containing both signal values and any modified data sets for this view. By default, the exported state includes all signal values (across all mark contexts) except for those bound to data pipeline transforms, and any data sets that were explicitly modified via triggers or the View API.
An options argument can be provided to control what internal state is collected. However, the options involve interacting with internal details of a Vega runtime dataflow and is intended for expert use only. The default options should suffice for state capture in most instances.
The options object supports the following properties:
Sets the state of signals and/or datasets in this view's backing dataflow graph. The state argument should be an object generated by the getState method. This method updates all implicated signals and data sets, invokes the run method, and returns this view instance.
# view.addSignalListener(name, handler) <>
Registers a listener for changes to the signal with the given name and returns this view instance. If the signal does not exist, an error will be raised. This method is idempotent: adding the same handler for the same signal multiple times has no effect beyond the first call.
When the signal value changes, the handler function is invoked with two arguments: the name of the signal and the new signal value. Listeners will be invoked when the signal value changes during pulse propagation (e.g., after view.run() is called).
Signal listeners are invoked immediately upon signal update, in the midst of dataflow evaluation. As a result, other signal updates and data transforms may have yet to update. If you wish to access the values of other signals, or update signal values and re-run the dataflow, use the runAfter method to schedule a callback that performs the desired actions after dataflow evaluation completes. Attempting to call the run method from within a signal listener will result in an error, as recursive invocation is not allowed.
To remove a listener, use the removeSignalListener method.
.addSignalListener('width', function(name, value) {
nsole.log('WIDTH: ' + value);
.width(500).run(); // listener logs 'WIDTH: 500'
# view.removeSignalListener(name, handler) <>
Removes a signal listener registered with the addSignalListener method and returns this view instance. If the signal does not exist, an error will be raised. If the signal exists but the provided handler is not registered, this method has no effect.
Methods for generating new event streams, registering event listeners, and handling tooltips. See also the hover method.
# view.events(source, type[, filter]) <>
Returns a new
EventStream
for a specified source, event type, and optional filter function. The
source should be one of "view" (to specify the current view), "window"
(to specify the browser window object), or a valid CSS selector string
(that will be passed to document.querySelectorAll). The event type should
be a legal DOM event type. If provided, the optional filter argument should
be a function that takes an event object as input and returns true if it
should be included in the produced event stream.
Typically this method is invoked internally to create event streams referenced within Vega signal definitions. However, callers can use this method to create custom event streams if desired. This method assumes that the view is running in a browser environment, otherwise invoking this method may have no effect.
# view.addEventListener(type, handler) <>
Registers an event listener for input events and returns this view instance.
The event type should be a string indicating a legal DOM event type
supported by vega-scenegraph
event handlers. Examples include "mouseover", "click", "keydown" and
"touchstart". This method is idempotent: adding the same handler for the
same event type multiple times has no effect beyond the first call.
When events occur, the handler function is invoked with two arguments: the
event instance and the currently active scenegraph item (which is null
if the event target is the view component itself).
All registered event handlers are preserved upon changes of renderer. For
example, if the View renderer type is changed from
"canvas" to "svg", all listeners will remain active. To remove a
listener, use the removeEventListener method.
.addEventListener('click', function(event, item) {
nsole.log('CLICK', event, item);
# view.removeEventListener(type, handler) <>
Removes an event listener registered with the addEventListener method and returns this view instance.
# view.addResizeListener(handler) <>
Registers a listener for changes to the view size and returns this view instance. This method is idempotent: adding the same handler multiple times has no effect beyond the first call.
When the view size changes, the handler function is invoked with two arguments: the width and height of the view.
.addResizeListener(function(width, height) {
nsole.log('RESIZE', width, height);
# view.removeResizeListener(type, handler) <>
Removes a listener registered with the addResizeListener method and returns this view instance.
# view.tooltipHandler(handler) <>
Gets or sets the handler function used to display tooltips, as defined via
the tooltip property of a mark. The default handler uses built-in browser
mechanisms by setting the "title" attribute of the Canvas or SVG element
containing the visualization. To use custom tooltips, a new handler function
can be provided to process tooltip events. If handler is null,
the tooltip handler will reset to the default.
The tooltip handler has the method signature handler(event, item, text),
where event is the triggering DOM mouseover or mouseout event, item
is the corresponding scenegraph item, and text is the tooltip text to
display (or null to hide tooltips).
uppress tooltips over the visualization, print to console instead
.tooltipHandler(function(event, item, text) {
nsole.log('TOOLTIP TEXT', text);
estore the default tooltip handler
.tooltipHandler(null);
Methods for exporting static visualization images. These methods can be invoked either client-side or server-side.
# view.toCanvas([scaleFactor]) <>
Returns a Promise that resolves to a canvas instance containing a rendered bitmap image of the view. The optional scaleFactor argument (default 1) is a number by which to multiply the view width and height when determining the output image size. If invoked in a browser, the returned Promise resolves to an HTML5 canvas element. If invoked server-side in node.js, the Promise resolves to a node-canvas Canvas instance.
# view.toSVG([scaleFactor]) <>
Returns a Promise that resolves to an SVG string, providing a vector graphics image of the view. The optional scaleFactor argument (default 1) is a number by which to multiply the view width and height when determining the output image size.
# view.toImageURL(type[, scaleFactor]) <>
Returns a Promise
that resolves to an image URL for a snapshot of the current view. The type
argument must be one of 'svg', 'png' or 'canvas'. Both the png and
canvas types result in a PNG image. The generated URL can be used to create
downloadable visualization images. The optional scaleFactor argument
(default 1) is a number by which to multiply the view width and height when
determining the output image size.
enerate a PNG snapshot and then download the image
.toImageURL('png').then(function(url) {
r link = document.createElement('a');
nk.setAttribute('href', url);
nk.setAttribute('target', '_blank');
nk.setAttribute('download', 'vega-export.png');
nk.dispatchEvent(new MouseEvent('click'));
atch(function(error) { /* error handling */ });
Methods for accessing data sets and performing streaming updates.
Returns the data set with the given name. The returned array of data
objects is a live array used by the underlying dataflow. Callers that wish
to modify the returned array should first make a defensive copy,
for example using view.data('name').slice().
# view.change(name, changeset) <>
Updates the data set with the given name with the changes specified by the provided changeset instance. This method does not force an immediate update to the view: invoke the run method when ready.
.change('data', vega.changeset().insert([...]).remove([...]))
.run()
Internally, this method takes the provided ChangeSet and invokes Dataflow.pulse. See vega-dataflow for more.
# view.insert(name, tuples) <>
Inserts an array of new data tuples into the data set with the given name, then returns this view instance. The input tuples array should contain one or more data objects that are not already included in the data set. This method does not force an immediate update to the view: invoke the run method when ready. Insert can not be used in combination with the remove method on the same pulse; to simultaneously add and remove data use the change method.
Internally, this method creates a ChangeSet and invokes Dataflow.pulse. See vega-dataflow for more.
# view.remove(name, tuples) <>
Removes data tuples from the data set with the given name, then returns this view instance. The tuples argument can either be an array of tuples already included in the data set, or a predicate function indicating which tuples should be removed. This method does not force an immediate update to the view: invoke the run method when ready. Remove can not be used in combination with the insert method on the same pulse; to simultaneously add and remove data use the change method.
For example, to remove all tuples in the 'table' data set with a count
property less than five:
.remove('table', function(d) { return d.count < 5; }).run();
Internally, this method creates a ChangeSet and invokes Dataflow.pulse. See vega-dataflow for more.