Skip to content

Web Embedding

Jump to bottom
Wenbo Tao edited this page Nov 9, 2020 · 19 revisions

Integrating a Kyrix App into Your Web App

The Kyrix front-end produces a simple SVG visualization. You might want to integrate that SVG into another web application for various kinds of purposes. For example, you might want:

  • custom controls for pan & zoom (e.g. arrow keys for panning, plus/minus keys for zooming);
  • HTML filters to highlight objects on the canvas;
  • an HTML table showing game stats getting updated when the Kyrix NBA app jumps to another game;
  • and more...

To facilitate such integration, we have provided a set of APIs for your web application to embed and interact with a Kyrix application. See documentation below for setup instructions and API references.

First Step - Importing Dependent JS/CSS Files

To correctly render a Kyrix app in your web application, you need to import dependency files. Specifically, you need to import the following JS/CSS files:

  • A JS file that bundles all Kyrix front-end code. To get this file, run the following commands: 
    $ cd front-end/js
$ cat embed/API.js globalVar.js jump.js jumpAnimation.js parameter.js staticLayers.js zoom.js zoomButton.js pageOnLoad.js dynamicLayers.js > embed/all.js
$ cd embed/
$ rollup -c    # requires rollup (https://www.npmjs.com/package/rollup) to be installed (e.g. `npm install -g rollup`).
    You will then find kyrix.js in front-end/js/embed. Importing this file will expose a global namespace kyrix, which contains a set of APIs for embedding and interacting with a kyrix visualization (described in the following).
  • Other JS dependencies: see here
  • CSS dependencies: see here

See example imports in this example. In the future, we plan to package all needed JS files into one big JS file and have it served online.

Putting your Kyrix Vis into a <div>

Suppose you have a Kyrix back-end running at 127.0.0.1:8000 and serving a Kyrix app of your choice. By running kyrix.initializeApp("http://127.0.0.1:8000", div), you can put the SVG visualization of that Kyrix app into div, which can be any div in your web application.

See below for complete API references.

Two Examples

We provide two examples based on the NBA application and the USMap application. To run these two examples, you need to have the corresponding Kyrix application running, and change the server URL in the following two files: example_nba.html and example_usmap.html. Afterwards, you can just open the HTML file in a browser and start interacting with both the Kyrix vis and any HTML elements you can see.

API References

🔗 kyrix.initializeApp(serverAddr, div) <>

Attaches to div an <svg> element showing the kyrix app at serverAddr. serverAddr must start with http or https. div should be an HTML <div> element. Returns a JS promise that resolves when the <svg> is loaded (note - not necessarily rendered).

🔗 kyrix.getRenderDataOfLayer(viewId, layerId) <>

Returns the current data items of layer layerId of the canvas in view viewId.

🔗 kyrix.getRenderData(viewId) <>

Returns the current data items in view viewId. The returned object is an array with length equal to the number of layers in the canvas. The i-th element in the array is an array of data items of layer i of the current canvas in view viewId. This is a shortcut to calling getRenderDataOfLayer on all layers.

🔗 kyrix.on(evt, viewId, callback) <>

Registers a callback listener callback when an event of type evt happens in view viewId. evt can be one of the following: pan, zoom, jumpstart or jumpend. You can use aliases to register callbacks of the same type, e.g. pan.one, pan.two, etc. jumpstart listeners are called before the jump is started. jumpend listeners are called after the jump is completed. callback can be arbitrary JS functions. If callback is not specified, returns the current listener, if any. If callback is null, removes the current listener. jumpstart and jumpend callbacks can both take in an argument jump which is a "jump object" containing some useful information about the current jump.

🔗 kyrix.getGlobalVarDictionary(viewId) <>

Returns a dictionary containing useful status variables of view viewId. In the returned dictionary, there are the following:

  • curCanvas: an object containing lots of useful information about the current canvas (e.g. width, height, layers, etc);
  • curJump: an array of jump objects;
  • curStaticData: an array of arrays of data items of static layers in the current canvas. The i-th array is non-empty only if the i-th layer of the current canvas is static.
  • initialViewportX: the initial x canvas coordinate of the top-lefthand corner of the initial viewport;
  • initialViewportY: the initial y canvas coordinate of the top-lefthand corner of the initial viewport;
  • viewportWidth: the width of the view viewId;
  • viewportHeight: the height of the view viewId;

🔗 kyrix.triggerPan(viewId, panX, panY) <>

Programmatically pans in view viewId. The amount of panning along the X (Y) axis is panX (panY) pixels.

🔗 kyrix.triggerJump(viewId, selector, layerId, jumpId) <>

Programmatically triggers a jump. selector is a CSS selector selecting one HTML node that the "user" clicks on. If multiple nodes qualify, the first one is used. selector can also simply be the HTML node (which can be retrieved by displayOnlyFilteredNodes, for example). LayerId is the layer that this node is in. jumpId is the index of the jump (which can be looked up in getGlobalVarDictionary).

🔗 kyrix.triggerPredicate(viewId, predDict) <>

Reloads view viewId using a new set of predicates as specified by predDict. predDict is a JS object mapping from layer ids (e.g. layer0 orlayer3) to binary AND/OR/EQ expression trees. See Project.setInitialStates for an example of predDict.

🔗 kyrix.reRender(viewId, layerId, additionalArgs) <>

Re-runs the rendering function of layer layerId of the canvas in view viewId with additional arguments additionalArgs (will be merged with args).

🔗 kyrix.getObjectData(viewId) <>

Returns all data items bound to the HTML nodes in view viewId. The returned object is an array with length equal to the number of layers in the canvas. The i-th element in the array is an array of data items of layer i of the current canvas in view viewId. This is a shortcut to calling getObjectDataOfLayer on all layers.

🔗 kyrix.getObjectDataOfLayer(viewId, layerId) <>

Returns all data items bound to the HTML nodes in layer layerId of the canvas in view viewId. The returned data items differ from those returned by getRenderDataOfLayer in cases where the rendering function binds something other than the original input data items to HTML nodes. For example, some rendering functions aggregate original input data items into another set of data items, which are further bound to HTML nodes.

🔗 kyrix.filteredNodes(viewId, layerId, filterFunc) <>

Returns all HTML nodes in layer layerId of the canvas in view viewId that pass a filter function filterFunc.filterFunc should receive the data bound to an HTML node, and returns whether this node passes the filter.

🔗 kyrix.setFilteredNodesOpacity(viewId, layerId, filterFunc, opacity) <>

Sets the opacity to opacity (between 0 and 1) for all HTML nodes in layer layerId of the canvas in view viewId that pass a filter function filterFunc, and returns all HTML nodes that pass the filter. filterFunc should receive the data bound to an HTML node, and returns whether this node passes the filter.

🔗 kyrix.displayOnlyFilteredNodes(viewId, layerId, filterFunc) <>

Displays only HTML nodes in layer layerId of the canvas in view viewId that pass a filter function filterFunc, and returns all visible HTML nodes in this layer. filterFunc should receive the data bound to an HTML node, and returns whether this node passes the filter.

🔗 kyrix.getCurrentCanvasId(viewId) <>

Returns the id of the current canvas in view viewId.

🔗 kyrix.getViewSvg(viewId) <>

Returns an HTML <svg> element that is the root HTML node of view viewId.

🔗 kyrix.getMainSvg(viewId, layerId) <>

Returns an HTML <svg> element that is the root HTML node of layer layerIdof the canvas in view viewId.

🔗 kyrix.getCurrentViewport(viewId) <>

Returns the viewport location of view viewId. The returned object has four fields:

  • vpX: the x canvas coordinate of the top-lefthand corner of the viewport;
  • vpY: the y canvas coordinate of the top-lefthand corner of the viewport;
  • vpW: the width of the view viewId;
  • vpH: the height of the view viewId;

🔗 kyrix.addRenderingParameters(params) <>

Adds additional parameters params into the rendering parameters of the current Kyrix application. params will be seen as a JS dictionary, and will be merged with the current rendering parameter dictionary.

🔗 kyrix.getRenderingParameters(params) <>

Returns the rendering parameters of the current Kyrix application.

Clone this wiki locally