Combos

Combos can be used to combine nodes and links together to simplify the visualisation. To access the combo namespace, use chart.combo().

arrange(id, options)

Arranges the items inside a combo.

Items are arranged automatically (default) or manually. The available automatic options are:

lens - automatic arrangement with connected nodes next to each other. The default for circular combos.
concentric - circular arrangement with larger items at the centre.
grid - grid arrangement running from left to right, from the top down in the order in which they are added in the combo. The default for rectangular combos.
sequential - tree-like arrangement showing the sequence of links between distinct levels of nodes.

To stop items from being arranged automatically, set name to 'none'.

Multiple ids can be passed to the arrange() function: in this case, items inside open combos within the array will be arranged.

Return Object

Use the returned promise to know when the operation is complete.

Note: You must wait for the combine promise to be fulfilled before performing another chart function.

Parameters

id: string | string[]; The ids of the combos to be arranged.
options: ComboArrangeOptions; Options controlling the operation.

Returns Promise

A Promise. You must wait for the promise to be fulfilled before performing another chart function.

close(ids, options)

Closes the specified open combo/s, concealing the items inside.

Parameters

ids: string | string[]; The ids of the combos to be closed.
options: OpenCloseOptions; Options controlling the operation.

Returns Promise

A Promise. You must wait for the promise to be fulfilled before performing another chart function.

combine(comboDefinition, options)

Combines a number of nodes into one or more 'combo nodes'. A combo definition object defines which nodes should be included in these combos and how they should be displayed.

A combo can be created in one of two states:

closed (default) - items inside the combo are not visible.
open - items inside the combo are displayed inside a combo border on the chart.

To open a combo, set the open property on its definition object.

Any links that connect nodes outside the combo to nodes inside it are combined into 'combo links'.

Return Object

Use the returned promise to detect when the operation has completed. The fulfilled promise returns an array of the identities of the combo nodes created as the first argument.

Note: You must wait for the combine promise to be fulfilled before performing another chart function.

chart.combo().combine({ ids: [id1, id2] }).then((comboIds) => {
  // do more after combine
});

To create many combos at once, use an array of combo definitions.

chart.combo().combine(
  [{ ids: [id1, id2] }, { ids: [id3, id4] }]).then((comboIds) => {
  // do more after combine
});

You cannot combine items that already exist inside a combo.

Closed and open combo states should not be confused with hide() and show() chart functions. If you combine a mixture of hidden and shown nodes, the nodes inside the combo will remain hidden or shown as appropriate. If you combine only hidden nodes, the combo itself will be hidden.

Parameters

comboDefinition: ComboDefinition | ComboDefinition[]; A definition of the combo/s to create.
options: CombineOptions; Options controlling the operation.

Returns Promise

A Promise. You must wait for the promise to be fulfilled before performing another chart function.

find(ids, options)

Finds the ids of the combos that contain the given nodes, links or child combos.

Parameters

ids: string | string[]; The ids of the nodes, links or combos whose parents should be found.
options: ComboFindOptions; Options controlling how the find operates.

Returns string | null | (string | null)[]

The ids of the combos containing the given items, or null if not found.

info(id)

Finds every underlying node and link inside a combo or nest of combos, or null if the id is not a combo.

Parameters

id: string; The id of the combo.

Returns object | null

An object in the form:

{
  links:[link1, link2, ..],
  nodes:[node1, node2, ..]
}

isCombo(id, options)

Tests node or link ids to find out whether they are combo nodes or combo links. If a list of ids is used, it returns true if any of the items are combos.

The options argument defines which items to test. For example, to test whether a selection contains a combo node:

const selectionContainsNodeCombo = chart.combo().isCombo(chart.selection(), { type: 'node' });

Parameters

id: string | string[]; The id/s of the items to be tested.
options: IsComboOptions; Options controlling whether links or nodes are tested.

Returns boolean

True if any of the node or link id is a combo, false otherwise.

isOpen(id)

Tests whether an item is an open combo.

Parameters

id: string; The id of the item to be tested.

Returns boolean

True if the item id is an open combo, false otherwise.

open(ids, options)

Opens the specified combo/s so the contents are visible inside a combo border on the chart. To change the border style, set the openStyle options of chart.combo().combine.

Parameters

ids: string | string[]; The id/s of the combos to be opened.
options: OpenCloseOptions; Options controlling the open operation.

Returns Promise

A Promise. You must wait for the promise to be fulfilled before performing another chart function.

reveal(ids)

Gets or sets the list of revealed links.

Links which connect nodes inside a combo to nodes outside it are normally combined into a single link to reduce clutter. The reveal() function shows the original underlying links.

Calling reveal() with a parameter replaces the previous list of revealed links. Pass an empty array to clear all revealed links.

Parameters

ids: string | string[]; The id/s of the links to be revealed.

Returns string[]

The currently revealed links.

transfer(id, comboId, options)

Transfers the specified items into or out of a combo, increasing the size of the target combo as needed to fit its new contents.

Parameters

id: string | string[]; The id/s of nodes to be transferred into or out of a combo.
comboId: null | string; The id of the combo to transfer the items to, or null to transfer items out of the combo and onto the chart.
options: TransferOptions; Options controlling the transfer operation.

Returns Promise

A Promise. You must wait for the promise to be fulfilled before performing another chart function.

uncombine(id, options)

Uncombines the specified combo nodes. Items inside the combo(s) are displayed on the chart. Combo links that connect nodes inside the combo to nodes outside it are also uncombined.

When nodes are uncombined, their original position is used to place them in the same shape relative to the uncombined node.

Multiple ids can be passed to the uncombine() function: in this case, all combo nodes in the array will be uncombined.

You cannot uncombine nested items (combo nodes and combo links that exist inside other combos).

Return Object

Use the returned promise to know when the operation is complete.

Note: You must wait for the combine promise to be fulfilled before performing another chart function.

Parameters

id: string | string[]; The id/s of the combos to be uncombined.
options: UncombineOptions; Options controlling the uncombine operation.

Returns Promise

A Promise. You must wait for the promise to be fulfilled before performing another chart function.