API Reference

The components object has all the current components loaded by the KeyLines wrapper. Components are accessed via their DOM id:

KeyLines.components['canvasID'].zoom('in');

Components are not created directly, but via KeyLines.create().

Allows asynchronous functions to be used with callbacks. This function is for backwards compatibility only.

Calculates the coordinates of events relative to their target.

Sets the value of the crossorigin HTML attribute whenever KeyLines is trying to load an image from a third-party domain.

The function takes a callback function that should return the value of the HTML attribute as a string depending on your criterion. If corsAdapter() is not set or if the callback returns undefined, the crossorigin attribute defaults to 'anonymous'.

KeyLines.corsAdapter((url) => {
  if (url.startsWith('https://keylines.io/')) {
    return 'use-credentials';
  } else {
    return 'anonymous'
  }
});

Creates KeyLines components in your web page.

The create() function is asynchronous, and so returns a promise. If an error occurs, the error catch function will be called, passing the error parameter to it. Otherwise, the success function will be called with the result object as the new component or array of components.

// Load a single chart
KeyLines.create({ container: 'div1' })
  .then((result) => {
    chart = result;
  })
  .catch((err) => {
    // handle the error here
});
// Load two KeyLines components with a specific id
KeyLines.create([
    { container: 'chartDiv', type:'chart' },
    { container: 'timebarDiv', type:'timebar' }
])
  .then((result) => {
    [chart, timebar] = result;
})
  .catch((err) => {
    // handle the error here
});

Checks whether the current browser can show elements full screen.

To view the current state of browser support for the Fullscreen API with desktop and mobile devices, see Can I use Fullscreen API.

Use the toggleFullScreen() call to make an element full screen.

A helper to find the right Unicode character to use for the icon based on the class name:

let data = { id: 'user', type: 'node', fi: { t: KeyLines.getFontIcon('fas fa-user') } };   // retrieves the Unicode position

The getfontIcon() function is deprecated as you can set font icons directly:

let data = { id: 'user', type: 'node', fi: { t: 'fas fa-user' } };

This applies to both the t option on the fi property to set an icon, and the imageAlignment option to scale and position it.

See the Font Icons documentation for details.

The Graph engine can be used to perform traversals or other graph computations within a separate context from the chart. For more information see The Graph Engine.

Defines which runtime KeyLines will use when calling KeyLines.create().

Tells KeyLines where it can find various resources on your server. This function must be called before the KeyLines.create() function.

When many chart items use images from the same directory, the images path can be used to save repeated use of the directory path within the chart object.

By default the full path to images must be passed in the u parameter of nodes, e.g.,

const item = { t: 'label', u: '/path/to/very/deep/directory/person.png' };

Alternatively, using the images path:

// in the initialization code put this:
KeyLines.paths({ images: '/path/to/very/deep/directory/' });
// and in the item creation
const item = { t: 'label', u: 'person.png' };

The images path is also used for glyph images, the logo and the background watermark.

The images path must have a trailing slash (/) character.

Allows any given HTMLElement to be put in Full Screen mode, using the browser's full screen API.

Usually a containing div is made full screen, rather than the KeyLines component itself. You should change the sizes of any parts of the page in the handler function – this receives a boolean parameter which is true if new status is full screen, or false if not.

Note that this function does not support Promises.

Checks if the current device supports WebGL and meets the minimum requirements.

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.

// 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.

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.

Removes all items from the chart.

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

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.

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.

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()

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.

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' }
];
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);
}
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.

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
});

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 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 the links and nodes 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] }]
  }
}

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 links and nodes - 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.

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

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

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

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().

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

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

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, the annotation is also hidden.

To show items, call the show() function.

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.