Breaking changes are changes to the behaviour of an existing object, function, event, option, parameter or value in the API.
Some changes are minor enhancements that shouldn't adversely affect your code. In exceptional circumstances, we may make changes to behaviours in your existing implementation. The details below will help you make the necessary code changes.
Note: New API features that don't affect existing code are not breaking changes. They're described in Release Notes as Enhancements.
straighten option has now also been added to chart.combo().arrange(), to improve the consistency between layout and arrangement behaviour. It's true by default, meaning that combo arrangements now also have link offsets reset by default. To keep link offset behaviour unchanged, set straighten to false.The KeyLines bundle has been streamlined, and third-party resources have been removed. Specifically, the css, map, and pdf directories, along with some redundant files from the images and fonts directories have been removed.
Any required files are listed, with links, in the Leaflet Integration and PDF Export documentation sections, and can also still be accessed in the 7.8.1 Long Term Availability (LTA) release (or earlier).
In previous versions, it was possible to create a link which had id1 and id2 specified, but omitted type: 'link' in its definition. This link looked the same as regular links but didn't respond correctly to some user interactions.
From 8.0, we've improved validation of items and this is no longer possible. To create a link, you must always set id1, id2 and type: 'link'.
In previous versions, the default layout that was applied when running chart.layout() or chart.expand() was 'standard'.
From 7.0, the default layout is now organic as it is our most advanced force-directed layout.
The packing: 'adaptive', which is the default packing when running chart.expand(), now behaves differently when the function is run with a default layout.
This is because the default layout has changed from 'standard' to 'organic' and the packing behaviour is different for the two layouts:
If you want to use the default organic layout with a packing behaviour similar to the previous behaviour, specify fix: 'nonadjacent' in the options object.
Alternatively, if you want to continue using the standard layout and keep the previous packing behaviour, you can set the layout explicitly to 'standard' when running chart.expand().
The default packing option for chart.layout() is now 'circle'. To restore the previous behaviour, specify packing: 'rectangle' in the options object.
d propertyIn previous versions, KeyLines would deep clone the d property value every time the property was imported to the chart model or retrieved from it:
// the d property on node 'a' is set and its value is cloned
var d = { value: 1 };
chart.setProperties({ id: 'a', d });
d.value = 2;
console.info(chart.getItem('a').d.value); // 1From 7.0, KeyLines no longer clones the object and the data inside the d property is instead retained on the node:
// the d property on node 'a' is set and its value is not cloned
var d = { value: 1 };
chart.setProperties({ id: 'a', d });
d.value = 2;
console.info(chart.getItem('a').d.value); // 2This new behaviour, which improves performance and memory usage, affects the following KeyLines functions that can accept or retrieve d properties: chart.animateProperties(), chart.createLink(), chart.each(), chart.expand(), chart.filter(), chart.foreground(), chart.getItem(), chart.load(), chart.merge(), chart.serialize(), chart.setItem(), chart.setProperties().
To restore the previous behaviour, deep clone the object containing the d property before passing it to KeyLines.
In previous versions, asynchronous functions could either provide a callback parameter or return a promise.
From 7.0, async functions are promisified by default to align with modern standards. As a result, we've removed KeyLines.promisify() from the API, Typescript and documentation.
If you are already using KeyLines with promises, you don't need to change your code. You can, however, remove your call to KeyLines.promisify() as it has no effect. If you are using KeyLines with TypeScript, you need to remove KeyLines.promisify() as you will see a build error that the function has been removed from the type definitions.
See our Asynchronous JavaScript documentation for more details about promises.
The KeyLines.callbacks() function can be used to continue using KeyLines with callbacks. This wrapper function returns a KeyLines object that works with both callbacks and promises so that you can easily gradually update your code to use promises. We recommend migrating to promises as soon as possible.
See the Using KeyLines with callbacks documentation for more details.
Note that the following breaking changes were introduced in 7.0 for callback users:
Previously, some errors from KeyLines could be handled synchronously in a try/catch statement. From 7.0, synchronous error handling is no longer available for asynchronous functions. If you want to add special error handling when using callbacks, you should listen for unhandled exceptions instead:
// browser
window.addEventListener('error', function(err) {
// do something with the error
// the error may still be shown in the console depending on the browser
});// Node and Modern JS
process.on('uncaughtException', (err)=> {
// do something with the error
});Previously, using asynchronous getter/setter functions as a setter also returned the current value. From 7.0, setters no longer return the value. To retrieve it, call the getter:
chart.options({ minZoom: 0.01 });
const currentOptions = chart.options();In previous versions, shape nodes were a special node type with w and h (width and height) set that was drawn in the chart background under regular nodes and links.
In 7.0, we've removed shape nodes from the public API as they have been superseded by more modern rectangular combos and rectangular nodes. If your code previously contained shape nodes with w and h set, these nodes will now be drawn as rectangular nodes in the node layer.
If you want to continue using shape nodes, you need to:
w and h setshape TypeScript definition with node TypeScript definitionNote that it's not possible to use both legacy shape nodes and regular rectangular nodes simultaneously in your chart.
From 6.0, the default expand behaviour has been changed to make use of the adaptive layout features released in 5.10. Calling expand() with default options will now only make changes to your chart that are needed to adapt to the incoming changes. The exact changes in defaults are:
packing: 'rectangle' in the expand options object.true. Note that tidy is deprecated. Use the packing option instead. To restore the previous behaviour, specify tidy: false in the expand options object.'adaptive'. To restore the previous behaviour, specify fix: 'nonadjacent' in the expand options object.true. To restore the previous behaviour, specify consistent: false in the expand options object.For users of the bind() events engine, it should be called from within a mousedown event handler.
false. To restore the previous behaviour, specify drag: { links: true }.true. To restore the previous behaviour, specify zoom: { adaptiveStyling: false }.Some events used with the bind() API have modified behaviour. Most of these are enhancements. Consider migrating to the on() API instead.
Ctrl + Click on MacOS now fires the 'context-menu' event instead of the 'click' event.
Selection is now updated after a click instead of a pointer-down / mousedown event.
To prevent default selection, use the selection-change / selectionchange event.
chart.bind('dragstart', function (type, id) {
const selection = chart.selection();
const idsBeingDragged = selection.includes(id) ? selection : [id];
// etc
});Unlike previous versions, KeyLines 5.0 loads images asynchronously, so images are added to the chart as soon as they're available.
Asynchronous functions that load image data into the chart, such as chart.load() and chart.setProperties(), are returned before image loading is complete Their callbacks/promises are resolved once images are loaded. See Asynchronous JavaScript for more details.
In most cases, you couldn't view insecure images from different domains in earlier KeyLines versions due to CORS security restrictions. One exception was images shown in KeyLines Canvas mode. These could be rendered but not exported or cut out into circular shapes.
In KeyLines 5.0 and later, all insecure images will be marked as missing. This means KeyLines will be consistently clear about which images can be exported. For details of how to make sure all images are secure, see Cross-Origin Images (CORS).
One effect of this is that if you download demos from this site and run them directly from the file system, you'll no longer see any images in the chart. We always recommend serving downloaded demos from a web server instead of the file system.
chart.setProperties() no longer removes properties that are set to null or undefined. If your code previously used 'undefined' to test whether properties existed, you'll now also need to check for values.
chart.setProperties({ id: '1', t: null }, false, function () {
var item = chart.getItem('1');
console.log(item.t); // null
console.log(item.hasOwnProperty('t')); // true
});Following our deprecation announcement on 15 January 2018, the following node shape (sh) object property options are no longer available or supported:
If you want to customise node shapes, use font icons. For examples, see the Style Nodes demo.
Following our deprecation announcement on 15 January 2018, the horizontal links feature is no longer available or supported. As a result, the following link properties have been removed:
We've also removed the 'fanLength' chart option, previously used to configure horizontal links.
We've taken the properties 'glyphs' and 'transition' (used for the 'linkStyle' chart option) out of the 'LinkStyle' interface and moved them to a new interface 'LinkStyleOptions'.
In previous versions, double-clicking a combo had no effect. Now, double-clicking a combo toggles between open and closed states by default.
To prevent this behaviour, bind to the double-click event and return true. Note that to preserve the default behaviour of a double-click on the chart background causing a zoom, you should not return true in the case where the background is clicked. For example:
chart.on('double-click', function ({id}) {
return id !== null; // return false if the background is double-clicked; true otherwise
});We've added an 'items' option to chart.each. It lets you choose which items to iterate over when using combos. The options are:
To maintain existing behaviour, add items: 'toplevel' to the chart.each options object.
We've deprecated the 'combos' option on chart.filter and chart.foreground and replaced it with the 'items' option.
To maintain existing behaviour, if you're using:
The default option has changed from combos: false, to items: 'underlying'. If you were using the default setting in 3.8 and earlier, you need to explicitly set items: 'toplevel' to avoid a behaviour change.
chart.getItem now returns items inside combos. Previously, it returned null. To find out whether an item is inside a combo, use chart.combo().find.
chart.hide, chart.removeItem and chart.show now apply to items inside combos; previously they didn't. To find out whether an item is inside a combo, use chart.combo().find.
If your current KeyLines version has consistent: true set in chart.layout, you may get a different result the first time you run a layout after upgrading. This is a one-off breaking change: subsequent layouts will be consistent with your first result.
We've improved the following layouts:
In structural layout only, we've also improved the way nodes are arranged in individual groups to reduce the chance of them overlapping.
The new layout behaviour improves every use case we support, so there is no option to maintain the existing behaviour.
We've reduced the default hover time in the hover chart option from 1000 to 150 milliseconds. To maintain existing behaviour, call:
chart.options({hover: 1000})If you call chart.ping on a node inside a closed combo, KeyLines will now ping the first visible parent combo. If you want to maintain existing behaviour and not ping the parent, you must first use chart.combo().find and chart.combo().isCombo to determine whether the node is in a closed combo.
If you use chart.ping to animate a node or link, the animated effect now appears in front of any shapes on the chart. This new ping behaviour improves every use case we support, so there is no option to maintain existing behaviour.
When users select or drag nodes, they're now always drawn on top of unselected nodes and no longer hidden behind them. This new behaviour improves every use case we support, so there is no option to maintain the existing behaviour.
Microsoft stopped supporting these older versions back in January 2016. In KeyLines 3.5, we announced our intention to follow their direction. KeyLines support for IE9 and IE10 has now ended.
However, if your code parses the output from chart.serialize() and you use combos, chart.serialize().items will now include items contained in combos.
To iterate only over items not contained in combos, use chart.each() instead.