Class NVL

Class for a NVL instance.

Example

This is a basic setup for a NVL instance.

import { NVL } from '@neo4j-nvl/base'

const nodes = [{ id: '1' }, { id: '2' }]
const relationships = [{ id: '12', from: '1', to: '2' }]

const options = { initialZoom: 0.5 }

const callbacks = {
  onLayoutDone: () => console.log('Layout done')
}

const nvl = new NVL(document.getElementById('frame'), nodes, relationships, options, callbacks)

Constructors

constructor

new NVL(
    frame: HTMLElement,
    nvlNodes?: Node[],
    nvlRels?: Relationship[],
    options?: NvlOptions,
    callbacks?: ExternalCallbacks,
): NVL
Creates a new NVL instance.
Parameters
- frame: HTMLElement
  The DOM element to display the graph in.
- nvlNodes: Node[] = []
  An array of nodes.
- nvlRels: Relationship[] = []
  An array of relationships.
- options: NvlOptions = {}
  The options for the NVL instance.
- callbacks: ExternalCallbacks = {}
  Callbacks triggered on NVL events.
Returns NVL

Methods

addAndUpdateElementsInGraph

addAndUpdateElementsInGraph(
nodes?: Node[] | PartialNode[],
relationships?: Relationship[] | PartialRelationship[],
): void
Adds nodes and relationships to NVL and updates existing nodes and relationships.
Parameters
- nodes: Node[] | PartialNode[] = []
  An Array of nodes to be added or updated.
- relationships: Relationship[] | PartialRelationship[] = []
  An Array of relationships to be added or updated. To update nodes or relationships, they must have an id that matches the id of the node or relationship to be updated. Only the properties that are provided will be updated. If an existing property is not provided, it will not be changed.
Returns void
Example
Adding and updating nodes and relationships
```
import { NVL } from '@neo4j-nvl/base'

const nvl = new NVL(document.getElementById('frame'), [{ id: '0' }], [])

const nodes = [
  { id: '1', caption: 'Node 1', color: '#e04141' },
  { id: '2', caption: 'Node 2', color: '#e09c41' }
]
const relationships = [{ id: '12', from: '1', to: '2' }]
// Adds new nodes and relationships
nvl.addAndUpdateElementsInGraph(nodes, relationships)
// Updates an existing relationship
nvl.addAndUpdateElementsInGraph([], [{ id: '12', color: '#e0df41' }])
```

addElementsToGraph

addElementsToGraph(nodes: Node[], relationships: Relationship[]): void
Adds nodes and relationships in the current scene.
Parameters
- nodes: Node[]
  The nodes to be added.
- relationships: Relationship[]
  The relationships to be added.
Returns void

Remarks
Elements whose id already exists are skipped silently; use addAndUpdateElementsInGraph to add and update in one call.

deselectAll

deselectAll(): void

De-selects all nodes and relationships.

Returns void

destroy

destroy(): void

Removes the graph visualization from the DOM and cleans up everything.

Returns void

fit

fit(nodeIds: string[], zoomOptions?: ZoomOptions): void
Updates pan and zoom to fit the specified nodes in the viewport.
Parameters
- nodeIds: string[]
  The ids of the nodes to fit on the screen. Unknown ids are ignored; an empty array (or only unknown ids) does nothing. Pass every id to fit the whole graph.
- OptionalzoomOptions: ZoomOptions
  Specific options on how to transition the zoom.
Returns void
Remarks
Zoom is limited by ZoomOptions.minZoom / ZoomOptions.maxZoom and the minZoom / maxZoom / allowDynamicMinZoom options. See those for details.
Example
```
import { NVL } from '@neo4j-nvl/base'

const nodes = [{ id: '1' }, { id: '2' }]
const nvl = new NVL(document.getElementById('frame'), nodes, [])

// Fit the whole graph
nvl.fit(nodes.map((node) => node.id))
```

getContainer

getContainer(): HTMLElement

Provides the container DOM element the graph is rendered in.

Returns HTMLElement
The container element of the NVL instance.

getCurrentOptions

getCurrentOptions(): NvlOptions

Returns the current options.

Returns NvlOptions
The current options.

getHits

getHits(
    evt: MouseEvent,
    targets?: HitTestTarget[],
    hitOptions?: { hitNodeMarginWidth: number },
): NvlMouseEvent
Gets the nodes, relationships, and clusters that have been hit by a pointer event.
Parameters
- evt: MouseEvent
  The mouse event.
- targets: HitTestTarget[] = ...
  The graph elements to check for hits. Defaults to ['node', 'relationship', 'cluster'].
- hitOptions: { hitNodeMarginWidth: number } = ...
  Options for the hit test. hitNodeMarginWidth widens the node hit area in layout units.
Returns NvlMouseEvent
A NvlMouseEvent with the HitTargets property containing the nodes, relationships, and clusters that have been hit by the pointer event.
Remarks
Clusters are hit when the pointer is inside a cluster hull, including over its nodes. This is the way to react to cluster hover; the hover interaction handler only reports nodes and relationships.
Example
```
import { NVL } from '@neo4j-nvl/base'

const container = document.createElement('div')
const nvl = new NVL(container, [{ id: '0' }], [])

// 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)
})

// Cluster hover
container.addEventListener('mousemove', (evt) => {
  const cluster = nvl.getHits(evt, ['cluster']).nvlTargets.clusters[0]?.data
  console.log('hovered cluster:', cluster?.id)
})
```

getImageDataUrl

getImageDataUrl(options?: { backgroundColor?: string }): string
Returns the current view of the graph visualization canvas as a data URL.
Parameters
- options: { backgroundColor?: string } = {}
  The options for the image.
  - OptionalbackgroundColor?: string
    
    The background color of the data URL.
Returns string
A data URL of the current view of the graph visualization canvas.

getNodeById

getNodeById(id: string): Node
Returns the node data that is currently stored in the visualisation for a given id.
Parameters
- id: string
  The id of the node that should be returned.
Returns Node
The node or undefined if there is no node with the given id.

getNodePositions

getNodePositions(): (Node & Point)[]

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

Returns (Node & Point)[]
An array of node positions.

getNodes

getNodes(): NodeWithClientPosition[]

Returns all nodes that is currently stored in the visualisation. Each node includes layout coordinates (x, y) and a clientPosition in screen space.

Returns NodeWithClientPosition[]
The array of nodes.

getNodesOnScreen

getNodesOnScreen(): { nodes: Node[]; rels: Relationship[] }
Returns the nodes that are currently in the visualization. The rels property of the returned object is always empty.

Returns { nodes: Node[]; rels: Relationship[] }
An object containing the nodes and relationships in the visualization.
- nodes: Node[]
  
  The nodes in the visualization.
- rels: Relationship[]
  
  The relationships in the visualization.

getPan

getPan(): Point

Returns the current pan of the viewport, in layout coordinates.

Returns Point
The layout-space point shown at the center of the container.

See
NodeWithClientPosition for the layout-to-screen formula.

getPositionById

getPositionById(id: string): Node
Returns the node position that is currently stored in the visualisation for a given id.
Parameters
- id: string
  The id of the node position that should be returned.
Returns Node
The position information for the given id, or undefined if there is no such node. or the layout has not yet run with that node.

getRelationshipById

getRelationshipById(id: string): Relationship
Returns the relationship data that is currently stored in the visualisation for a given id.
Parameters
- id: string
  The id of the relationship that should be returned.
Returns Relationship
The relationship or undefined if there is no relationship with the given id.

getRelationships

getRelationships(): Relationship[]

Returns the relationships that are currently in the visualization.

Returns Relationship[]
An array of the relationships in the visualization.

getScale

getScale(): number

Get the current zoom level of the viewport.

Returns number
The current zoom level.

See
NodeWithClientPosition for the layout-to-screen formula.

getSelectedNodes

getSelectedNodes(): (Node & Point)[]

Gets the currently selected nodes.

Returns (Node & Point)[]
An array of all currently selected nodes and their positions.

getSelectedRelationships

getSelectedRelationships(): Relationship[]

Gets the currently selected relationships.

Returns Relationship[]
An array of all currently selected relationships.

getSvgDataUrl

getSvgDataUrl(options?: { backgroundColor?: string }): Promise<string>
Experimental
Returns the entire graph visualization as an SVG data URL.
Parameters
- options: { backgroundColor?: string } = {}
  Options for the SVG export
  - OptionalbackgroundColor?: string
    
    The background color of the SVG (defaults to transparent).
Returns Promise<string>
A Promise resolving to a data URL string representing the graph as SVG (data:image/svg+xml;...)
Example
```
import { NVL } from '@neo4j-nvl/base'

const nvl = new NVL(document.getElementById('frame'), [{ id: '0' }], [])

const renderSvg = async () => {
  const svgDataUrl = await nvl.getSvgDataUrl({ backgroundColor: '#ffffff' })
  const img = document.createElement('img')
  img.src = svgDataUrl
  document.body.appendChild(img)
}
```

getZoomLimits

getZoomLimits(): { maxZoom: number; minZoom: number }
Returns the effective zoom limits.

Returns { maxZoom: number; minZoom: number }
The current minZoom and maxZoom. minZoom can be lower than the configured option when NvlOptions.allowDynamicMinZoom let the graph zoom out further.
- maxZoom: number
  
  The highest zoom level the graph can currently reach.
- minZoom: number
  
  The lowest zoom level the graph can currently reach.

isLayoutMoving

isLayoutMoving(): boolean

Checks and returns whether the current layout is still in flux.

Returns boolean
Whether or not the layout is moving.

pinNode

pinNode(nodeId: string): void
Pins the specified node so it is not affected by layout forces.
Parameters
- nodeId: string
  The id of the node to be pinned.
Returns void

removeNodesWithIds

removeNodesWithIds(nodeIds: string[]): void
Removes the specified nodes from the current scene.
Parameters
- nodeIds: string[]
  The node ids to be removed. Adjacent relationships will also be removed.
Returns void

removeRelationshipsWithIds

removeRelationshipsWithIds(relationshipIds: string[]): void
Removes the specified relationships from the current scene.
Parameters
- relationshipIds: string[]
  The relationship ids to be removed.
Returns void

resetZoom

resetZoom(): void

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

Returns void

restart

restart(options?: NvlOptions, retainPositions?: boolean): void
Restarts the NVL instance.
Parameters
- options: NvlOptions = {}
  New NvlOptions for the NVL instance.
- retainPositions: boolean = false
  Whether or not to retain the current node positions. New options will be merged with current options
Returns void

saveFullGraphToLargeFile

saveFullGraphToLargeFile(
options?: { backgroundColor?: string; filename?: string },
): void
Saves the entire graph visualization canvas as a png to the client.
Parameters
- options: { backgroundColor?: string; filename?: string } = {}
  The filename and background color of the png.
  - OptionalbackgroundColor?: string
    
    The background color of the png file. The size of the png file will be as large as the entire graph at the default zoom level. Can result in a very large file.
  - Optionalfilename?: string
    
    The filename of the png file.
Returns void

saveToFile

saveToFile(options?: { backgroundColor?: string; filename?: string }): void
Saves the current view of the graph visualization canvas as a png to the client.
Parameters
- options: { backgroundColor?: string; filename?: string } = {}
  The filename and background color of the png.
  - OptionalbackgroundColor?: string
    
    The background color of the png file. The size of the png file will be the size of the canvas in the DOM.
  - Optionalfilename?: string
    
    The filename of the png file.
Returns void

saveToSvg

saveToSvg(options?: { backgroundColor?: string; filename?: string }): void
Experimental
Saves the entire graph visualization as an SVG file to the client.
Parameters
- options: { backgroundColor?: string; filename?: string } = {}
  Options for the SVG export
  - OptionalbackgroundColor?: string
    
    The background color of the SVG file.
  - Optionalfilename?: string
    
    The filename of the SVG file.
Returns void

setDisableWebGL

setDisableWebGL(disabled?: boolean): void
Experimental
Restarts NVL with or without WebGL support.
Parameters
- disabled: boolean = false
  Whether or not WebGL should be disabled.
Returns void

setLayout

setLayout(layout: Layout): void
Changes the layout type.
Parameters
- layout: Layout
  The Layout type.
Returns void

Remarks
The layout is re-run only when the type actually changes. Calling this with the current layout type is a no-op.

setLayoutOptions

setLayoutOptions(options: LayoutOptions): void
Updates the configuration of the current layout.
Parameters
- options: LayoutOptions
  The LayoutOptions configuration. Replaces the previous options.
Returns void

setNodePositions

setNodePositions(data: Node[], updateLayout?: boolean): void
Sets the node positions based on data provided.
Parameters
- data: Node[]
  The positions that the nodes should be set to.
- updateLayout: boolean = false
  Whether or not the current layout algorithm should update the graph after setting the node positions.
Returns void

Remarks
Ids that are not in the graph are skipped with a warning. This is the way to position nodes; do not set x and y on the nodes passed to addAndUpdateElementsInGraph or updateElementsInGraph. For node positions to be unaffected by layout algorithms, use the 'free' layout type or use pinNode to pin the nodes that should remain still.

setPan

setPan(panX: number, panY: number): void
Sets the zoom of the viewport to a specific value.
Parameters
- panX: number
  The desired panX value.
- panY: number
  The desired panY value.
Returns void

Remarks
When updating both the zoom level and pan coordinates, use setZoomAndPan instead of calling setZoom and setPan separately to avoid jittering.

setRenderer

setRenderer(renderer: string): void
Switches between rendering methods
Parameters
- renderer: string
  which rendering method to use
Returns void

setZoom

setZoom(zoomValue: number): void
Sets the zoom of the viewport to a specific value.
Parameters
- zoomValue: number
  The desired zoom level.
Returns void

Remarks
When updating both the zoom level and pan coordinates, use setZoomAndPan instead of calling setZoom and setPan separately to avoid jittering.

If the zoom level is outside of the range provided by the NvlOptions.minZoom and NvlOptions.maxZoom options, the zoom level will be set to the closest valid zoom level. If NvlOptions.allowDynamicMinZoom is set to true, the NvlOptions.minZoom option will be ignored of the current graph does not fit the viewport.

setZoomAndPan

setZoomAndPan(zoom: number, panX: number, panY: number): void
Sets the zoom and pan of the viewport to specific values.
Parameters
- zoom: number
  The desired zoom level.
- panX: number
  The desired panX value.
- panY: number
  The desired panY value.
Returns void

Remarks
When only updating zoom level or pan coordinates, use setZoom or setPan instead.

If the zoom level is outside of the range provided by the NvlOptions.minZoom and NvlOptions.maxZoom options, the zoom level will be set to the closest valid zoom level. If NvlOptions.allowDynamicMinZoom is set to true, the NvlOptions.minZoom option will be ignored of the current graph does not fit the viewport.

unPinNode

unPinNode(nodeIds: string[]): void
Un-pins the specified nodes so they are affected by layout forces again.
Parameters
- nodeIds: string[]
  The ids of the nodes to be un-pinned.
Returns void

Remarks
A settled force-directed layout does not restart on its own after un-pinning. Call setNodePositions with updateLayout: true to wake it up.

updateElementsInGraph

updateElementsInGraph(
nodes: Node[] | PartialNode[],
relationships: Relationship[] | PartialRelationship[],
): void
Updates relationships in the current scene with the provided array of nodes and relationships.
Parameters
- nodes: Node[] | PartialNode[]
  The updated nodes.
- relationships: Relationship[] | PartialRelationship[]
  The updated relationships. Ignores any nodes or relationships that do not exist in the current scene. To update nodes or relationships, they must have an id that matches the id of the node or relationship to be updated. Only the properties that are provided will be updated. If an existing property is not provided, it will not be changed.
Returns void
Example
Updating nodes and relationships
```
import { NVL } from '@neo4j-nvl/base'

const nodes = [{ id: '1' }, { id: '2' }]
const relationships = [{ id: '12', from: '1', to: '2' }]
const nvl = new NVL(document.getElementById('frame'), nodes, relationships)

// Updates an existing node and relationship
nvl.updateElementsInGraph([{ id: '1', selected: true }], [{ id: '12', color: '#e0df41' }])
```

Class NVL

Example

Index

Constructors

Methods

Constructors

constructor

Parameters

Returns NVL

Methods

addAndUpdateElementsInGraph

Parameters

Returns void

Example

addElementsToGraph

Parameters

Returns void

Remarks

deselectAll

Returns void

destroy

Returns void

fit

Parameters

Returns void

Remarks

Example

getContainer

Returns HTMLElement

getCurrentOptions

Returns NvlOptions

getHits

Parameters

Returns NvlMouseEvent

Remarks

Example

getImageDataUrl

Parameters

OptionalbackgroundColor?: string

Returns string

getNodeById

Parameters

Returns Node

getNodePositions

Returns (Node & Point)[]

getNodes

Returns NodeWithClientPosition[]

getNodesOnScreen

Returns { nodes: Node[]; rels: Relationship[] }

nodes: Node[]

rels: Relationship[]

getPan

Returns Point

See

getPositionById

Parameters

Returns Node

getRelationshipById

Parameters

Returns Relationship

getRelationships

Returns Relationship[]

getScale

Returns number

See

getSelectedNodes

Returns (Node & Point)[]

getSelectedRelationships

Returns Relationship[]

getSvgDataUrl

Parameters

OptionalbackgroundColor?: string

Returns Promise<string>

Example

getZoomLimits

Returns { maxZoom: number; minZoom: number }

maxZoom: number

minZoom: number

isLayoutMoving

Returns boolean

`Optional`backgroundColor?: string

`Optional`backgroundColor?: string

`Optional`backgroundColor?: string

`Optional`filename?: string

`Optional`backgroundColor?: string

`Optional`filename?: string

`Optional`backgroundColor?: string

`Optional`filename?: string