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

captionAlign?: "center" | "top" | "bottom"

The caption align

captionSize?: number

The caption text size

captions?: { styles?: ("bold" | "italic")[], value: string }[]

The caption text and font style

color?: string

The color to use for the node

disabled?: boolean

Whether or not the current node is disabled

hovered?: boolean

Whether or not the current node is hovered

icon?: string

The icon to display inside a node

id: string

The ID of the current node, must be unique across all nodes and relationships, and must be a string, and cannot be empty.

pinned?: boolean

Whether or not the current node is pinned

selected?: boolean

Whether or not the current node is selected

size?: number

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

captionAlign?: "center" | "top" | "bottom"

The caption align

captionSize?: number

The caption text size

captions?: { styles?: ("bold" | "italic")[], value: string }[]

The caption text and font style

color?: string

The color to use for the relationship

disabled?: boolean

Whether or not the current relationship is disabled

from: string

Node ID where the relationship starts from

hovered?: boolean

Whether or not the current relationship is hovered

id: string

The ID of the current relationship, must be unique across all nodes and relationships, and must be a string, and cannot be empty.

to: string

Node ID where the relationship points to

width?: number

The width of a relationship

Options

The following is a list of selected options that can be specified.

Property

Definition

allowDynamicMinZoom?: boolean

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 true.

intitalZoom?: number

Zoom value of the current viewport

layout?: "forcedirected" | "hierarchical"

The graph layout algorithm to be used.

maxZoom?: number

The maximum zoom level allowed. Defailt value is 10.

minZoom?: number

The minimum zoom level allowed. Default value is 0.075

minimapContainer?: HTMLElement

The DOM container in which to render the minimap

panX?: number

Initial pan x value of the viewport

panY?: number

Initial pan y value of the viewport

renderer?: "webgl" | "canvas"

Which renderer method to use

Callbacks

The following callbacks can be specified:

Property

Definition

onError?: ((error: Error) ⇒ void)

Triggered when NVL throws an error after initialization

onLayoutComputing?: ((isComputing: boolean) ⇒ void)

Triggered when an asynchronous layout calculation starts/stops

onLayoutDone?: (() ⇒ void)

Triggered when a layout is done moving

onLayoutStep?: ((p: Node[]) ⇒ void)

Triggered on each step of a layout

onWebGLContextLost?: ((webGLContextEvent: WebGLContextEvent) ⇒ void)

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

addAndUpdateElementsInGraph

Adds nodes and relationships to NVL and updates existing nodes and relationships

addElementsToGraph

Adds nodes and relationships in the current scene

currentOptions

Returns the current options

deselectAll

Deselects all nodes and relationships

destroy

Removes the graph visualization from the DOM and cleans everything up

fit

Updates pan and zoom to fit the specified nodes in the viewport

getContainer

Provides the container DOM element the graph is rendered in

getCurrentOptions

Returns the current options

getHits

Gets the nodes and relationships that have been hit by an event

getNodeById

Returns the node data that is currently stored in the scene for a given ID

getNodePosition

Fetches and returns the current positions of all nodes as an array of coordinates

getNodes

Returns the data that is currently stored in the scene

getNodesOnScreen

Returns the nodes that are currently in the scene

getPan

Returns the current pan of the viewport

getPositionById

Returns the node position that is currently stored in the scene for a given ID

getRelationshipById

Returns the relationship data that is currently stored in the scene for a given ID

getRelationships

Returns the relationships that are currently in the scene

getScale

Get the current zoom level of the viewport

getSelectedNodes

Gets the currently selected nodes

getSelectedRelationships

Gets the currently selected relationships

isLayoutMoving

Checks and returns whether the current layout is still in flux

pinNode

Pins the specified node so it is not affected by layout forces

removeNodesWithIds

Removes specified nodes from the current scene

removeRelationshipsWithIds

Removes specified relationships from the current scene

resetZoom

Resets the zoom of the viewport back to the default zoom level of 0.75

restart

Restarts the NVL instance

saveFullGraphToLargeFile

Saves the entire scene as a .png to the client

saveToFile

Saves the current view of the scene as .png to the client

setLayout

Changes the layout type

setLayoutOptions

Updates the configuration of the current layout

setNodePositions

Sets the node positions based on the data provided

setPan

Sets the zoom of the viewport to a specific value

setUseWebGLRenderer

Toggles between the WebGL and Canvas rendering

setZoom

Sets the zoom of the viewport to a specific value

setZoomAndPan

Sets the zoom and pan of the viewport to specific values

unPinNode

Unpins the specified nodes so it is affected by layout forces again

updateElementsInGraph

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.