Chart

Chart functions allow you to draw content on the chart surface, zoom and pan around the chart, and perform layouts. To obtain a chart object to call these functions on, use KeyLines.create.

animateProperties(items, options)

Allows custom animations to be made and chained together.

Pass a single item object (or an array of objects) in the form {id: id, propertyName1: value1, propertyName2: value2 }. Items with a matching id will be animated.

Animations can either be applied to numeric properties:

// first animate the node to (100, 100) in 300 milliseconds and then move another node to this position
chart.animateProperties({ id: 'id1', x: 100, y: 100 }, { time: 300 }).then(() => {
  return chart.animateProperties({ id: 'id2', x: 100, y: 100 }, { time: 500 });
});

Or to colours:

// changes the link colour to blue with an alpha blend of 0.5 in an animation lasting 300 ms
chart.animateProperties({ id: 'link1', c: 'rgba(0,0,255,0.5)' }, { time: 300 });

When animating properties in the top level object, you only need to specify the properties that you want to animate. When animating properties in the nested object, you need to specify both animated and unchanged properties:

chart.setProperties({ id: 'link1', fbc: 'yellow', t: 'link', t1: 'endLabel1', t2: 'endLabel2' });

// animating the nested fbc property for t1 and t2 requires repeating the t properties as well
chart.animateProperties([{ id: 'link1', w: 15, fbc: 'orange', t1: { t: 't1', fbc: 'red' }, t2: { t: 't2', fbc:'green' } }]);

See the relevant numeric and colour properties in Item Format.

Note: Animating properties is not supported in Advanced label styling for items inside the styled node label t object.

Parameters

items: Node | Link | Annotation | (Node | Link | Annotation)[]; The item/s whose properties are to be changed.
options: AnimatePropertiesOptions; Options to control the animation.

Returns Promise

arrange(name, items, options)

Places a set of nodes together in close proximity.

chart.arrange('grid', ['id1', 'id2', 'id3'], { fit: true, animate: true }).then(() => {
  // do more after arrange
});

The nodes are arranged in the specified shape in the order that they appear in the items array.

Parameters

name: "grid" | "circle" | "radial"; The arrangement to use.
items: string[]; An array of the ids of the nodes to arrange.
options: ArrangeOptions; Options to control the arrangement of the nodes.

Returns Promise

A Promise.

clear()

Removes all items from the chart.

Returns void

combo()

The combo namespace has methods for combining the nodes and links of a chart to simplify it. See Combo Functions.

Returns Combo

The combo namespace which has functions for combining items together.

contains(shape)

Deprecated

Returns an array of ids of all the nodes or shapes contained inside the given shape.

Shapes are legacy nodes that are drawn behind nodes and links. They are set by specifying w and h for nodes and setting the legacyShapeNodeBehaviour option to true.

Things to note:

If no nodes or shapes are contained within the parent shape, the function returns an empty array.
If one or both of w and h parent shape dimensions are set to 'auto', the function returns an empty array.
Hidden items are returned.
Open combos or their contents are not returned.
If the shape contains other items, their ids will be returned only if they are fully contained within the shape.

Parameters

shape: ShapeOptions; The definition of the shape.

Returns string[]

The ids of the items contained in the shape (if any).

createLink(id, linkId, options)

Creates a special type of drag that lets a user draw a new link starting from a specified node. As a result, it should always be called from within a drag-start event handler to ensure that the user is dragging:

chart.on('drag-start', (e) => {
  const { id, type } = e;
  if (type === 'node') {
    // override the default node dragger with create-link
    chart.createLink(id, 'newLink').then(() => {
      // do more after createLink
    });
  }
});

Note that this function allows the user to draw a new link during dragging. It does not create a new link immediately. To create a new link without user interaction, use setItem.

Parameters

id: string; The id of the starting node. This node will be the id1 of the new link.
linkId: string; The id to set on the new link.
options: CreateLinkOptions; Options to control the style of the link.

Returns Promise

A Promise that resolves with the id of the linked item, or null if the user did not create a link.

destroy()

Destroys the current instance of the chart, freeing any allocated resources.

Note: This action cannot be undone. Create a new chart instance with KeyLines.create() to access the chart namespace.

chart.destroy()

Returns void

each(options, handler)

Allows easy iteration over all the items in the chart. The handler is called with one parameter: the current item.

// write all the labels for each node to the console
chart.each({ type:'node' }, (item) => {
console.log(item.id, item.t);
});

For details of using chart.each() with combos, see the Iterating over items section in Combos Concepts.

Parameters

options: EachOptions; Options controlling how to iterate over the chart items.
handler: (item: Link) => void; The function to be called for each item in the chart.

Returns void

expand(items, options)

The expand() function is the easiest way to add new items to the chart. It performs a merge() followed by a layout().

const newItems = [
  { id: 'newNode', type: 'node', t: 'New Node' },
  { id: 'newLink', type: 'link', t: 'New Link', id1: 'newNode', id2: 'oldNode' }
];<br>chart.expand(newItems, { animate: true, layout: { fit: true } }).then(() => {
  // do more after expand
});

If no layout is specified, expand() will use the organic layout by default.

If you have a current filter applied to the chart and want to keep the filter state consistent when new items are added to the chart, use the filter option:

function myFilter(item) {
  return (item.d.value > 10);
}<br>chart.expand(newItems, {animate: true, filter: { filterFn: myFilter, type: "node" } }).then(() => {
  // do more after expand
});

If there are multiple links between two nodes, expand() will automatically apply an offset to the links.

Things to note:

The layout() function is not supported while using a Leaflet map.
You cannot change the ends of an existing link.
The radial layout may have non-intuitive results depending on the change of the network topology.
Setting the x and y properties when using expand() has no effect as layout() overwrites these positions.
You can set the parentId of new items to add them into a combo, but cannot change the parentId of pre-existing items. See Combos for more detail.

Parameters

items: ChartData | Node | Link | Annotation | (Node | Link | Annotation)[]; To be added to the chart, a choice of either:

KeyLines chart object.
A single item.
An array of items.
options: ExpandOptions; Options to control the expanding action of the nodes.

Returns Promise

A Promise object.

export(options)

This function produces images of the chart in raster (PNG, JPEG) or vector (SVG, PDF) format. Raster images can be exported in high-resolution quality by setting the fitTo options to high values.

The exported image is encoded in a blob URL which is passed to the fulfilled promise.

chart.export({
  type: 'pdf',
  extents: 'chart',
  fitTo: 'page',
  heading: 'PDF Report',
  doc: {
    size: 'legal',
    layout: 'landscape',
    margin: 0.5 * 72, // 0.5 inch margin
  },
  fonts: {
     'Font Awesome 5 Free Regular': { src: '../fonts/fontAwesome5/fa-regular-400.woff' },
     Raleway: { src: './fonts/Raleway/Raleway-Regular.ttf' },
  },
}).then((exportResult) => {
  // do something with the image
});

SVG and PDF export may require embedding font files for fonts, font icons and special characters to display correctly. Unavailable fonts are replaced with ‘sans-serif’ and unavailable font icons are embedded as PNG images. See Font embedding in SVG and Text in PDF for details.

To export into PDF, you need to add external dependencies into your application. See the documentation for PDF Export for details.

The logo, navigation controls and overview window are not exported.

Notes

We do not recommend running multiple exports in parallel.
If you reference an image outside the domain of the KeyLines library, your browser will display it, but won’t let KeyLines examine it or render it to a URL. See Cross-Origin Images.
For PNG and JPEG, the maximum resolution that can be successfully exported is determined by the combination of device/OS/browser and memory available. We do not recommend attempting to export images larger than 100 megapixels.
Exporting charts on a Leaflet map may exclude items from some custom Leaflet layers, including markers and shadows.

Return Object

Use the returned promise object to detect when the operation has completed. The return object is in the form of { url, warnings }, where:

url - Contains a blob URL of the exported file. This will be undefined if a custom PDFDocument has been specified in the doc option to allow adding to the document before it is finished.
warnings - An array containing any warning objects generated during the export.

chart.export({  type: 'svg' }).then(({ url, warnings }) => {
  warnings.forEach(warning => { console.log(warning.msg); }); // we can do more with these, e.g. only log a certain type of warning
  const snapshotLink = document.createElement('a'); // create the link to download the image
  snapshotLink.download = 'chart-export.svg';
  snapshotLink.href = url;
  snapshotLink.click();
  URL.revokeObjectURL(url); // important - remember to revoke the url afterwards to free it from browser memory
});

Parameters

options: ExportOptions; An options object to configure the export.

Returns Promise

A Promise with the result of the export.

filter(filterFn, options)

Allows items in the chart to be hidden or shown depending on your own criterion.

// this function filters out nodes with a value <= 10
// including those within combos.
function myFilter(item) {
  return (item.d.value > 10);
}
chart.filter(myFilter, { type: 'node' }).then((filterResults) => {
  // do more after filter
});

When type is set to 'node', 'link' or 'annotation', the function automatically shows or hides the connected items, so that:

any nodes that have only hidden links will also be hidden
any visible links will have nodes at both ends also visible
any annotations with subjects and subject-relative positioning that have only hidden subjects will also be hidden
any visible annotations will have their subjects also visible

If the type is 'all', you have fine control over the visibility of all items and the rules above do not apply.

Filtering with Combos

By default, the filter() function includes the contents inside the combos when considering what data should be visible in the chart.

The resolve value for the promise is an object containing a combos property, which describes the visible combos (combo links and combo nodes) which have been altered by the filtering process, as well as the visible items within the combo - i.e., those items that match the filter criteria.

A typical use for this property is to re-size, re-style, or change the glyphs of the visible combos based on their (filtered) contents.

chart.filter(timebar.inRange, {}).then((result) => {
  // Resize the combo nodes based on visible items within
  const nodeStyles = result.combos.nodes.map((comboInfo) => {
    return { id: comboInfo.id, e: Math.sqrt(comboInfo.nodes.length) };
  });
  return chart.animateProperties(nodeStyles);
});

If the combo itself becomes visible, it will appear in both the shown and combos properties. If the combo itself becomes hidden, it will only appear in the hidden property.

For more details, see the Filtering and foregrounding items section of the Combos Concepts page.

Return Object

Use the returned promise object to detect when the filter operation has completed. The return object describes items altered by the filter function:

shown items (with nodes/links/annotations properties as arrays of ids)
hidden items (with nodes/links/annotations properties as arrays of ids)
shown combos and items in combos (with combo ids and nodes/links properties as arrays of objects)

The form of the object is:

{
  shown:  { nodes: [...] , links: [...], annotations: [...] },
  hidden: { nodes: [...] , links: [...], annotations: [...] }
  combos: {
    nodes: [{ id: comboId, nodes: [node], links: [link] }]
    links: [{ id: comboId, links: [link] }]
  }
}

Parameters

filterFn: function; A function which takes an item as argument. Returns true if the item should be visible, false otherwise.
options: FilterOptions; Options to control the filtering.

Returns Promise

A Promise that resolves with result of the filter.

foreground(foregroundFn, options)

Allows nodes and links in the chart to be backgrounded or foregrounded depending on your own criteria.

// this function puts nodes with a value <=10 into the background
// including those inside of combos
function isForeground(item) {
  return (item.d.value > 10);
}
chart.foreground(isForeground, {}).then(() => {
  // do more after foreground
});

When using the type option 'node' or 'link', the function automatically changes the background state of connected items to keep the chart appearance clean. Backgrounded items are given an alpha value which can be set with the backgroundAlpha option.

At the end of the operation:

any nodes that have only background links will also be in the background
any foreground links will have both ends in the foreground

If the type is 'all', you have fine control over the background state of all the items - the rules above are not applied. This line of code will foreground all items in the chart:

chart.foreground((node) => true );

Return Object

Use the returned promise to detect when the foreground operation has completed. The return object describes exactly which items were put into the foreground or background and has the form:

{
  foreground: { nodes: [...] , links: [...] },
  background: { nodes: [...] , links: [...] }
}

For foreground or background objects, the nodes / links properties are arrays of ids.

For details on how to use foregrounding with combos, see the Filtering and foregrounding items and the Foregrounding open combos sections in Combos Concepts.

Parameters

foregroundFn: function; A function which takes an item as its argument, returning false if the item should be in the background, true otherwise.
options: ForegroundOptions; Options to control the foreground operation.

Returns Promise

A Promise that resolves with result of the foreground.

getAggregateInfo(id)

Beta

Returns aggregation information associated with the specified link(s).

Parameters

id: string | string[]; The link(s) being queried.

Returns AggregateInfo | null | (AggregateInfo | null)[]

An object containing the aggregation information associated with each specified link, or null if there is no link matching the id.

AggregateInfo

aggregateByProp

required

undefined | string

If an aggregate link: the key of the custom data on the child link's d property being used for aggregation.

aggregateByValue

required

any

If an aggregate link: the value of the custom data specified by aggregateByProp. All its child links have the same value of the property.

aggregateChildren

required

undefined | string[]

If an aggregate link: its child links.

aggregateDirection

required

undefined | "both" | "none" | "from" | "to"

If an aggregate link: the direction in which its child links are aggregated:

'from': direction arrow points from id1 to id2
'to': direction arrow points from id2 to id1
'both': direction arrows in both directions
'none': link aggregation is not based on direction

isAggregate

required

boolean

Whether the specified link is an aggregate link.

parentAggregate

required

undefined | string

If the link is a child of an aggregate, specifies its parent link.

getItem(id)

Returns a copy of the items in the chart which match the id.

Note:To update the items, use setProperties().

Parameters

id: string | string[]; The id string or the array of id strings of the items to be retrieved.

The item or array of items matched. Returns null if there is no item matching an id.

getItemInfoAt(x, y)

Returns information on the item at the specified view coordinates.

Note: This function is intended for use in integration tests. For fetching items from the chart, use getItem().

Parameters

x: number; The x position in view coordinates.
y: number; The y position in view coordinates.

Returns object

An object describing the id and subItem of the item at the specified coordinates.

getRelativeAnnotationPosition(id)

Returns the position of the annotation relative to its subjects. Can be useful e.g. when converting world-positioned annotations to subject-relative annotations.

Parameters

id: string; The id of the annotation.

Returns object | null

The annotation position relative to its subjects as an object with angle and distance properties. Returns null if annotation is not found or if it has no subjects.

getWorldAnnotationPosition(id)

Returns the position of the annotation in world coordinates. Can be useful e.g. when converting subject-relative annotations to world-positioned annotations.

Parameters

id: string; The id of the annotation.

Returns object | null

The annotation position in world coordinates as an object with x and y properties, or null if not found.

graph()

The graph object has methods for navigating the top level of your chart.

See KeyLines.getGraphEngine() to consider the underlying level of the chart.

Returns Graph

The graph representation of the chart.

hide(id, options)

Hides item or items with the id(s) specified.

Hiding nodes automatically hides any links that are connected only to the hidden nodes.

Hiding a combo node will hide all its child items.

Hidden links will not be considered when running a layout.

If all annotation subjects (nodes, links and combos) are hidden and the annotation has subject-relative positioning, the annotation is also hidden.

To show items, call the show() function.

Parameters

id: string | string[]; The ids of items to hide.
options: HideOptions; Options to control the hide operation.

Returns Promise

A Promise.

labelPosition(id, index)

Returns information about the label of the item with the specified id. Can be useful e.g. when overlaying text edit boxes over the chart surface. Does not return the label position for t1 or t2 labels on link ends.

Parameters

id: string; The identity of the item.
index: number; If the item is styled by an array of label objects, represents the index of the specific label object.

Returns object | null

An object containing label coordinate properties, or null if the items are hidden or don't exist. The coordinates are in view coordinates relative to the top left corner of the KeyLines HTML element.

{
  x1: valueX1, // left
  x2: valueX2, // right
  y1: valueY1, // top
  y2: valueY2, // bottom
  fs: value // font size at current zoom
}

layout(name, options)

The layout function positions the nodes of the chart.

The layouts are:

'organic': The default force-directed layout offering excellent performance and results for any type or size of data.
'sequential': lays out tree-like data in a traditional hierarchy structure, minimising crossed links.
'hierarchy': a simpler tree-like layout.
'lens': places the node in a circle-like grid, with connected nodes next to each other.
'radial': places nodes in concentric circles.
'structural': places nodes which are structurally similar together in the network.
Deprecated'standard': a force-directed graph layout which tries to keep link lengths consistent.

For more detail on our layouts, see Layout Basics.

Options can be passed in the second argument. For example:

chart.layout('organic', {
  mode: 'adaptive',
  animate: false
}).then(() => {
  // do more after layout
});

The layout is not performed on a Leaflet map.

Hidden items do not change their positions and are not considered by the layout function. When re-showing hidden items consider running a layout to ensure the chart looks good afterwards.

If you are using combos, be aware that layouts only consider nodes that are on the top-level of the chart. For more detail on chart levels, see Combos Concepts.

Return Object

The layout call is asynchronous - the function will return before the layout has completed. To discover the progress of the layout use the progress event. Use a promisified function to detect when the layout has finished.

The arrange() function is an alternative way to position nodes. It places nodes in close proximity into a specified shape.

Parameters

name: "organic" | "sequential" | "hierarchy" | "lens" | "radial" | "structural" | "standard"; The name of the layout to be invoked. The default is 'organic'.
options: LayoutOptions; Options to control features of the layout.

Returns Promise

A Promise.

load(data)

Replaces the chart data with the new specified data and dereferences any existing objects in the chart.

Note that the data argument is a JavaScript Object, not a JSON string. It should have the properties specified for the relevant Item Format.

const data = { type: 'LinkChart', items: [
  { id: 'node1', type: 'node', t: 'Node 1' },
  { id: 'node2', type: 'node', t: 'Node 2' },
  { id: 'link', type: 'link', t: 'Link', id1: 'node1', id2: 'node2' },
  { id: 'annotation', type: 'annotation', subject: 'node1', t: { t: 'Annotation' } },

]};<br/>chart.load(data).then(() => {
  // do something else
});

If there are multiple links between two nodes, load() will automatically apply an offset to the links.

You can set the parentId of new nodes to add them into a combo. See Combos for more details.

When using Leaflet Integration, call load() before displaying the Leaflet map. See Special behaviour for more details.

Parameters

data: ChartData; The data to load into the chart.

Returns Promise

A Promise.

lock(val, options)

Locks and unlocks the chart. When the chart is locked, end-user interactions using mouse, keyboard and touch cannot alter the state of the chart.

Note that the API can continue to modify the chart while it is locked.

To determine the current state of the chart, call lock() with no arguments.

Parameters

val: boolean; If true, the chart is locked.
options: LockOptions; Options to control the chart's behaviour while locked.

Returns boolean

True if the chart is locked, false otherwise.

map()

The map namespace has methods for displaying the chart on a Leaflet map. See Map Functions.

Returns Map

The map namespace object.

merge(items)

Adds new items to the chart, or modifies the properties of existing items. Properties of any items matched will be replaced with the new item properties.

Merging does not lay out the chart - if you want the chart to be laid out afterwards, call chart.layout() once the promise is resolved.

const newItems = [
  { id: 'newNode', type: 'node' },
  { id: 'newLink', type: 'link', id1: 'newNode', id2: 'existingNode' },  // new link connecting a new node with existing one
  { id: 'newAnnotation', type: 'annotation', subject: 'existingNode' },  // new annotation added on an existing node
];<br>chart.merge(newItems).then(() => {
  // do something else
});

You can set the parentId of new items to add them into a combo, but cannot change the parentId of pre-existing items. See Combos for more detail.

If there are multiple links between two nodes, merging will automatically apply an offset to the links. Note that you cannot change the ends of an existing link.

Parameters

items: ChartData | Node | Link | Annotation | (Node | Link | Annotation)[]; To be added or modified in the chart, a choice of either:

KeyLines chart object.
A single item.
An array of items.

Returns Promise

A Promise.

off(name, handler)

Detaches an event handler function for one or more events attached to the chart using the on() function.

chart.off('progress', progressEventHandler);

If no handler is supplied, all handlers for the specified event are detached. If no event name is supplied, all event handlers for all events are detached.

Parameters

name: Chart Event; The name of the event to be detached from, e.g., 'click'. Use 'all' to detach from all events.
handler: Function; The event handler that was supplied to the on() call.

Returns void

on(name, handler)

Attaches an event handler function for one or more Chart Events to the chart.

function progressEventHandler(task, progress) {
  // use progress to set progress bar value
}
chart.on('progress', progressEventHandler);

To detach event handlers, use off().

See Events Basics for more details.

Parameters

name: Chart Event; The name of the event to listen for, e.g., 'click'. Use 'all' to listen to all events.
handler: function; The event handler to call when the event occurs.

Returns void

options(val)

Sets or gets the current display and interaction options. See Chart Options.

Note that using this promisified function as a getter still returns an object in a synchronous way. See Special Cases: getters and setters for more detail.

chart.options({ minZoom: 0.01 });

Parameters

val: ChartOptions; Controls the chart options.

Returns object | Promise

Getter: The current options.

Setter: A Promise object.

pan(direction, options)

Pans the chart in the direction specified.

Parameters

direction: "left" | "right" | "up" | "down" | "selection"; Controls how to pan the chart:

'up' / 'down' / 'left' / 'right' - Pans the chart as specified.
'selection' - Pans the centre of the viewport to the centre of the selected items.
options: PanOptions; Options to control the pan operation.

Returns Promise

A Promise.

ping(id, options)

Adds an animated effect to a specified node or link, and then removes it again. To animate nodes and links in other ways, use the animateProperties() function.

Ping and nodes

The function adds a halo to nodes. Animation expands the halo's radius and width to specified values while decreasing the alpha value of its specified colour, giving a fade effect.

Ping does not affect the ha0-9 properties used for displaying other halos on nodes.

Ping and links

The function adds an animated effect on links that's similar to halos on nodes. The animation expands from the outline of the link to a specified width while decreasing the alpha value of its specified colour, giving a fade effect. Note that you cannot apply halo properties to links.

Ping items in combos

If an item is in a closed combo when it is pinged, the ping appears on the closed combo.

Parameters

id: string | string[]; The ids of items to be animated.
options: PingOptions; Options to control the animation.

Returns Promise

A Promise.

removeItem(id)

Removes item or items with the id(s) specified. Note that there is no event to detect items being removed from the chart.

Parameters

id: string | string[]; The id string or array of id strings of items to remove.

Returns void

selection(val)

Sets or gets the current chart selection as an array of ids. Selected items are drawn on top of non selected ones. Any link whose end is selected will also be drawn on top.

Note that hidden items cannot be selected.

Parameters

val: string[]; Ids of items to be selected. Note that annotations cannot be selected.

Returns string[]

The current selection as a list of item ids.

serialize()

Returns a complete serialization of the current chart content in the form specified by the object properties section.

The serialized chart can be loaded back in by using the chart.load function. This can be used for saving the chart state in a database or for implementing features like undo or redo.

You can also load in serialized data with merge() or expand(), but be aware that when merging data with combos, only the underlying items will be loaded, and not combos or combo links. See Combos Concepts for more detail.

Calling chart.serialize() during animations, or when transitioning to and from a Leaflet map, may cause transient node positions to be saved into the serialized data.

Note: We do not recommend parsing the results of chart.serialize as a way to get items from the chart. Instead, use chart.each to iterate over items and return an array.

Returns object

The representation of the chart state in the form of a KeyLines chart object.

setContainer(element)

Sets the location of the chart in the DOM. Pass null as the argument to hide it completely.

Things to note:

You must specify the container parameter in KeyLines.create() to use setContainer().
While the container is set to null, all drawing and animations are paused, and you cannot transition to and from a Leaflet map.

chart.setContainer('chartContainer');

Parameters

element: null | string | HTMLElement; The id string or DOM element of the parent container that the chart should be appended to.

Returns void

setItem(item)

Creates a new item in the chart with the specified properties. The item should have the properties specified in Item Format, and must include all the desired properties of the new item including its type, either 'node' or 'link'. If there is an existing item in the chart with the same id, it is replaced and none of its properties are retained.

chart.setItem({ id: 'node1', type: 'node', c: 'blue', t: 'new label' }).then(() => {
  // do something else
});

Note that if the new item is a link, both of its end nodes must already be present in the chart. It is not possible to add links without ends, and you cannot change the ends of an existing link.

You can set the parentId of a new item to add it into a combo, but cannot change the parentId of a pre-existing item. See Combos for more detail.

To change some of the properties of an existing item without replacing it, use setProperties().

Note: Using setItem to add an additional link doesn't apply the automatic offset to the link. Use merge() if you want this.

Parameters

item: Node | Link; The item to set in the chart.

Returns Promise

A Promise.

setProperties(items, useRegEx)

Changes properties of items in the chart.

Use it to change properties of multiple items in a single call - see Data Manipulation for more details.

Accepts a single item object (or an array of items) in the form {id: id, propertyName1: value1, propertyName2: value2 }. Items with a matching id will take the new values.

Setting useRegEx = true treats the ids passed in as regular expressions. This is useful for global settings, for example to set the font size across the whole chart:

chart.setProperties({ id: '.', fs: 8 }, true);

Regular expressions are always evaluated with the 'i' (case-insensitive) and 'm' (multiline) modifiers set, and ids should be passed as strings (not regular expression objects).

Note that the new value will completely replace the previous one, even for Glyphs, Font Icons or properties for other item formats where the value is an object or an array.

If you want to update or merge object or array properties, the recommended way is to get the current value, modify it and set it back. For example:

const item = chart.getItem('item-id');

// now add a new property to the current one
const data = item.d;
data.myNewProperty = 'new value';

// and update the chart
chart.setProperties({ id: item.id, d: data });

When changing properties in the top level object, you only need to specify the properties that you want to change. When changing properties in the nested object, you need to specify both changing and unchanged properties:

// changing top level properties of a link
chart.setProperties({ id: 'link1', fbc:'orange', t: 'link', t1: 'endLabel1', t2: 'endLabel2', });

// changing the nested fbc property for t1 and t2 requires repeating the t properties as well
chart.setProperties([{ id: 'link1', t1: { t: 'endLabel1', fbc:'red' }, t2: { t: 'endLabel2', fbc:'green' } }]);

Notes:

You cannot change the ends of an existing link.
Setting hi to true to hide a combo node also hides the items inside. For more details, see the Hiding and showing items section in Combos Concepts.

Parameters

items: Node | Link | Annotation | (Node | Link | Annotation)[]; The ids of items to be changed and the properties to be changed.
useRegEx: boolean; Whether the ids are to be treated as regular expression strings. The default is false.

Returns Promise

A Promise.

show(id, options)

Shows (unhides) the items specified by the id parameter.

Calling show() on a combo will also show the items inside it. Calling show() on an item inside a hidden combo or a nest of combos will show that item and its parent(s).

Hiding nodes with chart.hide() or chart.filter() automatically hides their links, but calling show() to unhide the nodes does not automatically reinstate the hidden links. To do that for the nodes specified in the id parameter, set showLinks to true.

Hiding all annotation subjects using chart.filter() automatically hides their subject-relative positioned annotations, but calling show() to unhide at least one subject does not automatically reinstate the hidden annotations. To do that for the subjects specified in the id parameter, set showAnnotations to true.

Parameters

id: string | string[]; The ids of items to show.
options: ShowOptions; Options to control the show operation.

Returns Promise

A Promise.

toDataURL(width, height, options)

Deprecated

This function is deprecated. Use the chart.export() function which supports more output types.

Returns a data URL of the chart image as the first argument of the fulfilled promise: a base64 encoded PNG image string will be passed to the fulfilled promise.

chart.toDataURL(300, 200, {}).then((dataURL) => {
  // do something with the image
});

The navigation controls and overview window are not drawn into the image.

If you reference an image that's on a different domain to the KeyLines library, your browser will display it, but won’t let KeyLines examine it or render it to a data URL. For details on how to fix this, see Cross-Origin Images (CORS).

toDataURL behaves slightly differently for charts on a Leaflet map:

Only the current visible viewport will be captured in the data URL, which means the width, height and options.fit parameters will be ignored.
Some layers within the Leaflet map, including markers and shadows, will not be included in the data URL.

Parameters

width: number; The width of the required image in pixels. The default is the width of the chart element. Not supported for a Leaflet map.
height: number; The height of the required image in pixels. The default is the height of the chart element. Not supported for a Leaflet map.
options: ToDataURLOptions; Options to control how the image is created.

Returns Promise

A Promise that resolves to a base64 encoded PNG image string.

viewCoordinates(x, y)

Converts world coordinates (positions of items within the chart) to screen coordinates in the current view. This depends on the current view settings (zoom and pan). View coordinates are relative to the top left corner of the chart.

Parameters

x: number; The x position in world coordinates.
y: number; The y position in world coordinates.

Returns object

An object containing the view coordinates.

Coordinates

x

required

number

The horizontal coordinate.

y

required

number

The vertical coordinate.

viewOptions(options, transition)

Sets or gets the current chart view options, which covers the zoom setting and viewport location.

For a Leaflet map, view options must be set through the Leaflet API.

Note that using this promisified function as a getter still returns an object in a synchronous way. See Special Cases: getters and setters for more detail.

Parameters

options: ViewOptions; Controls the view options.
transition: Transition; Options to control the transition between view states.

Returns object | Promise

Getter: The current view options.

Setter: A Promise object.

worldCoordinates(x, y)

Converts screen coordinates (in the current view) to the coordinates which are used to represent the position of items within the chart. This depends on the current view settings (zoom and pan).

Parameters

x: number; The position in screen pixel coordinates relative to the left side of the chart.
y: number; The position in screen pixel coordinates relative to the top of the chart.

Returns object

An object containing the world coordinates.

Coordinates

x

required

number

The horizontal coordinate.

y

required

number

The vertical coordinate.

zoom(how, options)

Zooms the chart in the manner specified.

Parameters

how: "height" | "one" | "selection" | "fit" | "in" | "out"; Controls how to zoom the chart:

'in' / 'out' - Zooms the chart in/out as specified.
'one'- Zooms the chart in/out so that node sizes match the canvas pixel size. Equal to chart.viewOptions({ zoom: 1 }).
'fit'- Fits the chart or the specified ids to window.
'height' - Fits the height of the chart or of the specified ids to window.
'selection' - Fits the selected items to window.
options: ZoomOptions; Options to control the zoom operation.

Returns Promise

A Promise.