Migration guides

Ogma@6.0 migration guide

Ogma@6.0 introduces some changes to the transformation API that may require adjustments in your codebase. This guide outlines the key modifications and how to adapt your code accordingly.

Import syntax

Ogma no longer provides a default export. You must now use a named import:

Old code:

import Ogma from '@linkurious/ogma';

New code:

import { Ogma } from '@linkurious/ogma';

This change aligns with modern JavaScript/TypeScript best practices:

• Better tree-shaking: Named exports allow bundlers to statically analyze which exports are used and eliminate dead code more effectively.
• Explicit imports: Named exports make it clear exactly what is being imported, improving code readability and reducing ambiguity.
• TypeScript consistency: The TypeScript community recommends named exports as they work more predictably with type inference and refactoring tools.
• ESM compatibility: Named exports are the standard pattern in ES modules and avoid interoperability issues between CommonJS and ESM.

Animations

Animations control changed quite a bit:

• Individual transformations do not have a duration and easing param anymore
• Transformations have a new param: animates, if set to false, it acts as the duration:0 from previous versions.
• The global animations duration and easing are controlled through the ogma.transformations.setAnimation function.

Why those changes?

• In Ogma 4, the animations of the transformations applied sequentially, leading to confusing transitions.
• In Ogma 5, we introduced the merged animations for the transformations: Ogma computes the final state of the visualisation and animates once for all transformations.
• In Ogma we reflect this change of behaviour in the API.

So code like this:

ogma.transformations.addNodeFilter({
    ...
    duration: 250,
    easing: 'quadraticInOut'
});

Becomes:

ogma.transformations.setAnimation({
    duration: 250,
    easing: 'quadraticInOut'
});
ogma.transformations.addNodeFilter({
    ...
});

Easy Grouping

This new feature aims to make it easier for developers to use the Grouping feature: instead of declaring NodeGrouping transformations and think in terms of group Sets, groups hierarchy, you can build your grouping by hand using two functions:

• nodeList.group() which group together a list of nodes
• node.addSubGraph() which replaces the node with a group containing the subGraph passed in param

See it in action

Discontinuation of deprecated features

Events API

The deprecated events API has been discontinued in favor of a simplified event handling system. Instead of using method-based event subscriptions, use the standard on API with JavaScript event names.

Old code:

ogma.events.onClick(someFunction);
ogma.events.onDoubleClick(someFunction);
ogma.events.onHover(someFunction);

New code:

ogma.on('click', someFunction);
ogma.on('doubleclick', someFunction);
ogma.on('mouseover', someFunction);

This change provides a more consistent and flexible API that aligns with standard JavaScript event patterns.

Complete list of removed methods

Deprecated method	Replacement
General
removeListener(fn)	off(fn)
Graph events
onNodesAdded(fn)	on('addNodes', fn)
onBeforeNodesRemoved(fn)	on('beforeRemoveNodes', fn)
onNodesRemoved(fn)	on('removeNodes', fn)
onEdgesAdded(fn)	on('addEdges', fn)
onBeforeEdgesRemoved(fn)	on('beforeRemoveEdges', fn)
onEdgesRemoved(fn)	on('removeEdges', fn)
onGraphCleared(fn)	on('clearGraph', fn)
Node drag events
onNodeDragStart(fn)	on('nodesDragStart', fn)
onNodeDragProgress(fn)	on('nodesDragProgress', fn)
onNodeDragEnd(fn)	on('nodesDragEnd', fn)
onDrop(fn)	on('drop', fn)
Selection events
onNodesSelected(fn)	on('nodesSelected', fn)
onNodesUnselected(fn)	on('nodesUnselected', fn)
onEdgesSelected(fn)	on('edgesSelected', fn)
onEdgesUnselected(fn)	on('edgesUnselected', fn)
Data change events
onNodeDataChange(fn)	on('updateNodeData', fn)
onEdgeDataChange(fn)	on('updateEdgeData', fn)
onAnimate(fn)	on('animate', fn)
Mouse events
onMouseMove(fn)	on('mousemove', fn)
onMouseButtonDown(fn)	on('mousedown', fn)
onMouseButtonUp(fn)	on('mouseup', fn)
onClick(fn)	on('click', fn)
onDoubleClick(fn)	on('doubleclick', fn)
onMouseWheel(fn)	on('mousewheel', fn)
onHover(fn)	on('mouseover', fn)
onUnhover(fn)	on('mouseout', fn)
Drag/gesture events
onDragStart(fn)	on('dragStart', fn)
onDragProgress(fn)	on('dragProgress', fn)
onDragEnd(fn)	on('dragEnd', fn)
onGestureStart(fn)	on('gestureStart', fn)
onGestureProgress(fn)	on('gestureProgress', fn)
onGestureEnd(fn)	on('gestureEnd', fn)
View/render events
onRendererStateChange(fn)	on('rendererStateChange', fn)
onZoomStart(fn)	on('zoomStart', fn)
onZoomProgress(fn)	on('zoom', fn)
onViewChanged(fn)	on('viewChanged', fn)
Geo events
onNodesConnected(fn)	on('connectNodes', fn)
onGeoModeEnabled(fn)	on('geoEnabled', fn)
onGeoModeDisabled(fn)	on('geoDisabled', fn)
onGeoModeLoaded(fn)	on('geoLoaded', fn)
Layout events
onLayoutStart(fn)	on('layoutStart', fn)
onLayoutComplete(fn)	on('layoutEnd', fn)
onLayoutComputed(fn)	on('layoutComputed', fn)
Tooltip events
onTooltipShown(fn)	on('tooltipShow', fn)
onTooltipHidden(fn)	on('tooltipHide', fn)
Transformation events
onTransformationEnabled(fn)	on('transformationEnabled', fn)
onTransformationDisabled(fn)	on('transformationDisabled', fn)
onTransformationSetIndex(fn)	on('transformationSetIndex', fn)
onTransformationDestroyed(fn)	on('transformationDestroyed', fn)
onTransformationRefreshed(fn)	on('transformationRefresh', fn)

Parse API

The instance-based parse API has been replaced with static methods on the Ogma class. This change allows you to parse graph data before creating an Ogma instance, improving performance and flexibility.

Old code:

const ogma = new Ogma();
ogma.parse.gexf(gexfString).then((graph) => ogma.setGraph(graph));

New code:

const graph = await Ogma.parse.gexf(gexfString);
const ogma = new Ogma();
ogma.setGraph(graph);

Ogma@5.3 migration guide

Ogma@5.3 introduces some changes to the transformation API that may require adjustments in your codebase. This guide outlines the key modifications and how to adapt your code accordingly.

Node grouping

Ogma@5.3 introduces a new way to increase the performance of the layout by merging running it once for all the nodes inside of the groups. This is done by returning the layout options in the onGroupUpdated callback.

So if you had a code like this:

ogma.group({
  groupIdFunction: (node) => ...,
  showContents: true,
  onGroupUpdated: (group) => {
    return ogma.layouts.force({ nodes: group });
  }
});

You should now return the layout options instead of the layout itself:

ogma.group({
  groupIdFunction: (node) => ...,
  showContents: true,
  onGroupUpdated: (group) => {
    return { layout: 'force', params: {...} };
  }
});

Same goes for the onGroupsUpdated callback on ogma.transformations:

ogma.transformations.onGroupsUpdated((groups) => {
  return { layout: 'force', params: {...} };
});

Alternatively, you can return a promise that resolves to the final nodes positions:

ogma.group({
  groupIdFunction: (node) => ...,
  showContents: true,
  onGroupUpdated: (group) => {
    return yourPlacementFunction(group);
  }
});

For more details you should refer to the API documentation of the grouping transformation options.

GPU layout

One of the main benefits of the new grouping API is that it allows you to use the GPU layout for the groups. This is done by returning the gpu layout in the onGroupUpdated callback:

ogma.group({
  groupIdFunction: (node) => ...,
  showContents: true,
  onGroupUpdated: (group) => {
    return { layout: 'force', params: { gpu: true, ...} };
  }
});

So in addition to the huge performance boost that is delivered by the new grouping API, you can also benefit from the GPU layout for the groups to make it even faster and bring better quality to the compound nodes.