documentationfor yFiles for HTML 3.0.0.4
Migrating to 2.6 from 2.5Migrating to 2.4 from 2.3

Migrating to 2.5 from 2.4

Changes in the library files

The libraries are provided as tgz files

The yFiles libraries are provided as tgz files. They now can be used directly without running the setup script. Developers who have used the library js files directly instead of the npm modules now have to unpack the library files. To do so, please switch to the folder /tools/unpack-library-files/ folder and execute the npm task unpack-library-files:

npm run unpack-library-files

Alternatively, you can unpack the tgz file manually and rename the resulting folder package to es-modules or umd.

The tgz files are now located in the lib and lib-dev folders

The npm package files are now located in the lib and lib-dev folders:

  • lib/yfiles-<version>.tgz

  • lib-dev/yfiles-<version>+dev.tgz

  • lib/yfiles-umd-<version>.tgz

  • lib-dev/yfiles-umd-<version>+dev.tgz

Before, they were located in the es-modules and umd sub folders. The path to yFiles has to be adjusted in the dependencies in the package.json files.

The yFiles npm package files now use the correct semver syntax for their versions

Developers who use the yFiles development library should note that the 'dev' suffix is appended with a + now. The library has now to be referenced as yfiles-<version>+dev.tgz.

One TypeScript definition file for both VS Code and WebStorm

The TypeScript definition files can now be used in both WebStorm and VS Code. There is no need to use the npm-module-vscode script anymore.

Clickable Handles and Handle Behavior

The IHandle interface has a new method handleClick. This method must be implemented by custom handle implementations.

When starting to drag the handle of a selected item, the handle is not replaced anymore by a new handle instance provided for the selected item. Previously, this happened automatically, regardless of whether necessary to support use cases where state changes should result in a different handle instance. Now, GraphEditorInputMode's requeryHandles method has to be called explicitly when changes are made that affect handles that are potentially already visible. Alternatively, a proxy implementation can be used that dynamically dispatches to new instances on its own when required.

The HandleInputMode class does not initialize a handle drag as soon as the handle is pressed, anymore. Instead, it waits until the draggedRecognizer or draggedRecognizerTouch is triggered. When pressed, the mutex is already acquired, which discards other concurrent input modes. This can be turned off by setting the requestMutexOnPress property to false.

ModelManagers must be installed now

Due to the new install and uninstall methods of the ModelManager class, the following of its members have been changed:

  • The CanvasComponent constructor parameter has been removed. Instead, you can call the new install method with the CanvasComponent as parameter. Similarly, the CanvasComponent constructor parameters of the derived classes have been removed, too.

  • Its existing protected methods install and uninstall have been renamed to installItem and uninstallItem.

  • Its protected methods add and remove have been renamed to addItem and removeItem.

  • The optional SelectionModel and Model parameters of HighlightIndicatorManager and SelectionIndicatorManager have been removed from the constructors, too. Instead, you can set the corresponding properties directly.

Setting a new model manager to GraphComponent's selectionIndicatorManager, highlightIndicatorManager, or focusIndicatorManager properties, will call install and set the necessary properties automatically.

Interactive node and edge creation can be asynchronous

  • The return values of CreateEdgeInputMode's createEdge method and of the function which can be set as edgeCreator have been changed to IEdge | Promise<IEdge|null> | null.

  • The return value of the function which can be set to GraphEditorInputMode's nodeCreator property has been changed to INode | Promise<INode|null> | null.

WebGL2

  • The WebGL2NodeEffect enum was renamed to WebGL2Effect since it can now be used for effects of nodes, edges, and labels.

  • The createNodeEffectScaleAnimation, createNodeEffectFadeAnimation, and createNodeEffectPulseAnimation methods of WebGL2GraphModelManager were renamed to createEffect*Animation.

  • The animation API of the WebGL2GraphModelManager was refined to be more consistent and flexible. All animation factory methods now have a timing parameter of type WebGL2AnimationTiming.

  • In WebGL2 rendering mode, handles and selection indicators no longer adopt styling specified with CSS classes. Instead, more comprehensive styling options are available with the new Theme class and the style properties of the WebGL2SelectionIndicatorManager, WebGL2HighlightIndicatorManager, and WebGL2FocusIndicatorManager classes.

  • The WebGL2GraphModelManager.getWebGL2LabelStyle method may now also return an instance of WebGL2IconLabelStyle (but the default implementation does not).

Other API Changes

  • The direction parameter of the BfsAlgorithm.getLayers method now uses the new BfsDirection enum instead of the TraversalDirection enum. TraversalDirection got a new member that does not apply to this method, and BfsDirection reflects the options previously available. Note that this is expert API and you typically use the Bfs class, instead.

  • The Exception.innerException property was renamed to cause to conform to recent additions of the ECMAScript spec.

  • The NodeLabelingPolicy enum has been moved from yfiles.tree to yfiles.layout. The reason is that the policy is now not only supported by BalloonLayout but also by CircularLayout, RadialLayout and CactusGroupLayout.

  • The type of the EdgeCellInfo.cellSegmentInfos property was changed from YList to CellSegmentInfo[].

  • HierarchicLayoutData's subComponents property is replaced by the new subcomponents property with a different signature. The new property uses instances of the new SubcomponentDescriptor class to define subcomponents, and the layout algorithm responsible for a component is now specified via the new SubcomponentDescriptor.layoutAlgorithm property.

  • Similarly, the data provider keys HierarchicLayout.SUB_COMPONENT_ID_DP_KEY and HierarchicLayout.SUB_COMPONENT_LAYOUT_ALGORITHM_DP_KEY are replaced by the new key HierarchicLayout.SUBCOMPONENT_DESCRIPTOR_DP_KEY that assigns instances of the new SubcomponentDescriptor class to nodes.

  • The data provider key TemporaryGroupNodeInsertionStage.COMPONENT_LAYOUT_ALGORITHM_DP_KEY was removed and the name of the key TemporaryGroupNodeInsertionStage.COMPONENT_ID_DP_KEY was changed to TEMPORARY_GROUP_DESCRIPTOR_DP_KEY. The newly added TemporaryGroupDescriptor class now specifies groups and the applied recursive group layout algorithm.

  • The property components of class TemporaryGroupNodeInsertionData has been renamed to temporaryGroups. Also, its value type has been changed to TemporaryGroupDescriptor.

  • The protected ImageNodeStyleRenderer.getPreserveAspectRatio method has been removed in favor of the new ImageNodeStyle.aspectRatio property.

  • The NavigationInputMode.adjustGroupNodeLocation method has now an additional parameter expandedSize that specifies the size of the group node when it is expanded.

  • ILookup's lookup method is now generic and infers its return type from the given parameter. TypeScript implementations must be adapted accordingly. Nothing changes for JavaScript.

  • The Fill.freeze, Stroke.freeze, DashStyle.freeze, and GradientStop.freeze methods now return their respective containing type.

  • The License.value property has now the more specific type Record<string, unknown> instead of object.

  • The node parameter of IGraph's setIsGroupNode method is now correctly annotated as not-null. The documentation already stated that this method throws an error if the node is null.

Changes of Default Behavior

  • The semantics of TraversalDirection's BOTH enum value used by the Neighborhood and Bfs algorithms has been changed and does not ignore the direction anymore, but now returns a union of the successor and the predecessor results instead. The old behavior can be restored by using the new UNDIRECTED enum value. Consequently, the default values of the traversalDirection properties of both the Neighborhood and the Bfs algorithms have been changed from BOTH to UNDIRECTED.

  • Formatting text with the WORD_ELLIPSIS option still wraps at word boundaries, but now trims character by character to better match the CSS text-overflow behavior and make more efficient use of the remaining space.

  • The lists returned by methods GraphPartition.getCells, DynamicObstacleDecomposition.getCells and DynamicObstacleDecomposition.getObstacles are no longer unmodifiable.

  • With the graph builder classes, label bindings which do not provide label data (or provide null) no longer add empty labels. Instead, no label will be added. Similarly, for label sources, no label will be added for data items for which the LabelCreator.textProvider returns null. This involves the following API changes:

    • The LabelCreator.addLabel method can return null if no label is added.

    • The LabelCreator.updateLabel method now returns a boolean value: true if the label has been updated, false if the label should be removed.

Removed unused methods and properties

The following methods and properties have been removed since they had no effect. Usages of them can be safely removed: DataProviderAdapter.defined, GraphEditorInputMode.shouldClickCreateNode, NodeAggregation.multiThreadingAllowed, and NodeAggregationAlgorithm.multiThreadingAllowed.

Deprecations

  • The styles BevelNodeStyle, ShinyPlateNodeStyle, and PanelNodeStyle classes and their renderers are now deprecated. Their appearance is rather outdated, and some of them are not very configurable. For group nodes, have a look at the new GroupNodeStyle class.

  • IEnumerable's firstOrDefault and lastOrDefault methods are now marked as deprecated since they duplicate the find and findLast methods, and the latter had the same name as the corresponding methods of the native JavaScript Array.

Migrating to 2.6 from 2.5Migrating to 2.4 from 2.3