Base library
Initialization
The base library is the base of NVL. It is a JavaScript class which is framework-agnostic. It takes five arguments:
-
the container to renderer
-
an array of nodes
-
an array of relationships
-
options objects
-
object with callbacks
Nodes
Every node must have an ID and it can be any unique string. Additionally, the following optional properties can be provided:
Property |
Definition |
|
The caption align |
|
The caption text size |
|
The caption text and font style |
|
The color to use for the node |
|
Whether or not the current node is disabled |
|
Whether or not the current node is hovered |
|
The icon to display inside a node |
|
The ID of the current node, must be unique across all nodes and relationships, and must be a string, and cannot be empty. |
|
Whether or not the current node is pinned |
|
Whether or not the current node is selected |
|
The size of a node |
Relationships
Relationships must have a unique ID, a from, and a to property which must correspond to existing node IDs in the graph. Additionally, the following properties can be specified:
Property |
Definition |
|
The caption align |
|
The caption text size |
|
The caption text and font style |
|
The color to use for the relationship |
|
Whether or not the current relationship is disabled |
|
Node ID where the relationship starts from |
|
Whether or not the current relationship is hovered |
|
The ID of the current relationship, must be unique across all nodes and relationships, and must be a string, and cannot be empty. |
|
Node ID where the relationship points to |
|
The width of a relationship |
Options
The following is a list of selected options that can be specified.
Property |
Definition |
|
Whether or not to dynamically allow decreasing minimum zoom value if current graph does not fit on screen at minimum zoom.
Note that when set to true, zoom and fit operations will allow zooming out further than the minimum zoom value if the graph does not fit on screen.
When set to false, zoom and fit operations will stop at the minimum zoom value, even if the full graph does not fit on screen at that zoom level.
Default value is |
|
Zoom value of the current viewport |
|
The graph layout algorithm to be used. |
|
The maximum zoom level allowed. Defailt value is 10. |
|
The minimum zoom level allowed. Default value is 0.075 |
|
The DOM container in which to render the minimap |
|
Initial pan x value of the viewport |
|
Initial pan y value of the viewport |
|
Which renderer method to use |
Callbacks
The following callbacks can be specified:
Property |
Definition |
|
Triggered when NVL throws an error after initialization |
|
Triggered when an asynchronous layout calculation starts/stops |
|
Triggered when a layout is done moving |
|
Triggered on each step of a layout |
|
Triggered when WebGL context is lost |
Interactivity
To interact with a graph, NVL provides methods that help get the nodes and relationships that have been hit by a pointer event.
The method takes an event and returns the event with the HitTargets
property containing the nodes and relationships that have been hit by the event.
This is a basic example:
import { NVL } from '@neo4j-nvl/base'
const container = document.getElementById('frame')
const nodes = [{ id: '1' }, { id: '2' }]
const relationships = [{ id: '12', from: '1', to: '2' }]
const nvl = new NVL(container, nodes, relationships)
// Get the nodes and relationships that have been hit by a pointer event.
container.addEventListener('click', (evt) => {
const { nvlTargets } = nvl.getHits(evt)
console.log('clicked elements:', nvlTargets)
})
Based on the type of event, you can make updates to NVL through methods. The following NVL methods are available:
Method |
Defintion |
|
Adds nodes and relationships to NVL and updates existing nodes and relationships |
|
Adds nodes and relationships in the current scene |
|
Returns the current options |
|
Deselects all nodes and relationships |
|
Removes the graph visualization from the DOM and cleans everything up |
|
Updates pan and zoom to fit the specified nodes in the viewport |
|
Provides the container DOM element the graph is rendered in |
|
Returns the current options |
|
Gets the nodes and relationships that have been hit by an event |
|
Returns the node data that is currently stored in the scene for a given ID |
|
Fetches and returns the current positions of all nodes as an array of coordinates |
|
Returns the data that is currently stored in the scene |
|
Returns the nodes that are currently in the scene |
|
Returns the current pan of the viewport |
|
Returns the node position that is currently stored in the scene for a given ID |
|
Returns the relationship data that is currently stored in the scene for a given ID |
|
Returns the relationships that are currently in the scene |
|
Get the current zoom level of the viewport |
|
Gets the currently selected nodes |
|
Gets the currently selected relationships |
|
Checks and returns whether the current layout is still in flux |
|
Pins the specified node so it is not affected by layout forces |
|
Removes specified nodes from the current scene |
|
Removes specified relationships from the current scene |
|
Resets the zoom of the viewport back to the default zoom level of 0.75 |
|
Restarts the NVL instance |
|
Saves the entire scene as a .png to the client |
|
Saves the current view of the scene as .png to the client |
|
Changes the layout type |
|
Updates the configuration of the current layout |
|
Sets the node positions based on the data provided |
|
Sets the zoom of the viewport to a specific value |
|
Toggles between the WebGL and Canvas rendering |
|
Sets the zoom of the viewport to a specific value |
|
Sets the zoom and pan of the viewport to specific values |
|
Unpins the specified nodes so it is affected by layout forces again |
|
Updates relationships in the current scene with the provided array of nodes and relationships |
The following is an example that selects nodes when they are clicked and de-selectes nodes when clicking on empty space in the scene:
const nodes = [{ id: '0' }, { id: '1' }]
const rels = [{ id: '10', from: '0', to: '1' }]
const myNvl = new NVL(parentContainer, nodes, rels)
parentContainer.addEventListener('click', (e) => {
const { nvlTargets } = myNvl.getHits(e)
if (nvlTargets.nodes.length > 0) {
myNvl.addAndUpdateElementsInGraph([{ id: nvlTargets.nodes[0].data.id, selected: true }], [])
} else {
myNvl.addAndUpdateElementsInGraph(
nodes.map((node) => ({ ...node, selected: false })),
[]
)
}
})
If you don’t want to implement traditional graph interaction behavior from the start, NVL also provides a collection of interaction handlers.