Home

Awesome

<p align="center"> <img src="https://raw.githubusercontent.com/kieler/elkjs/master/doc/elk_logo_with_text.svg" height="100"> </p>

npm version

The Eclipse Layout Kernel (ELK) implements an infrastructure to connect diagram editors or viewers to automatic layout algorithms. This library takes the layout-relevant part of ELK and makes it available to the JavaScript world. ELK's flagship is a layer-based layout algorithm that is particularly suited for node-link diagrams with an inherent direction and ports (explicit attachment points on a node's border). It is based on the ideas originally introduced by Sugiyama et al. An example can be seen in the screenshot below.

Note that elkjs is not a diagramming framework itself - it computes positions for the elements of a diagram.

elkjs is the successor of klayjs.

Demonstrator

You can see elkjs live in action in conjunction with TypeFox's sprotty diagramming framework. In case elklive happens to be down you can use the published docker container to run and host it yourself.

FAQs and Recurring Issues

The following list includes some recurring topics that may have been addressed in issues already:

Installation

The latest released version:

npm install elkjs

Development version based on ELK's master branch.

npm install elkjs@next

Releases and Versioning

Releases are partly synchronized with ELK's versions: the minor version number is always the same but the revision number may diverge. For instance, elkjs 0.3.0 equals the functionality of ELK 0.3.0 but elkjs 0.3.2 may be different from ELK 0.3.2. This is necessary as there may be fixes that solely concern elkjs and should be released independently of ELK.

Files

The library consists of two main files:

Two further files are provided:

Example

A small example using node.js, for further use cases see the next section.

const ELK = require('elkjs')
const elk = new ELK()

const graph = {
  id: "root",
  layoutOptions: { 'elk.algorithm': 'layered' },
  children: [
    { id: "n1", width: 30, height: 30 },
    { id: "n2", width: 30, height: 30 },
    { id: "n3", width: 30, height: 30 }
  ],
  edges: [
    { id: "e1", sources: [ "n1" ], targets: [ "n2" ] },
    { id: "e2", sources: [ "n1" ], targets: [ "n3" ] }
  ]
}

elk.layout(graph)
   .then(console.log)
   .catch(console.error)

Note that in case you get errors, you may want to switch to the non-minified version to get a proper stack trace.

Layout Options

You can use layout options to configure the layout algorithm. For that you attach a layoutOptions object to the graph element that holds key/value pairs representing the desired layout options. See, for instance, root in the example above. It is possible to only use the suffix of a layout option: algorithm instead of org.eclipse.elk.layered. However, if the suffix is not unique the layout option may be ignored. To be safe, you should always start the layout options with the elk. part. A list of all options and further details of their exact effects is available in ELK's documentation.

It is possible to pass global layout options as part of the layout method's second argument. The options are then applied to every graph element unless the element specifies the option itself:

elk.layout(graph, {
  layoutOptions: { ... }
})

Additionally, ELK's constructor accepts an object with layout options that is used with every layout call that does not specify layout options:

const elk = new ELK({
  defaultLayoutOptions: { ... }
})

Usage

Since laying out diagrams can be a time-consuming job (even for the computer), and since we don't want to freeze your UI, Web Workers are supported out of the box. The following examples illustrate how the library can be used either with and without a Web Worker.

node.js

const ELK = require('elkjs')
// without web worker
const elk = new ELK()

elk.layout(graph)
   .then(console.log)

const ELK = require('elkjs')
// with web worker
const elk = new ELK({
  workerUrl: './node_modules/elkjs/lib/elk-worker.min.js'
})

elk.layout(graph)
   .then(console.log)

Since version 10.x, node.js comes with a worker threads implementation that is similar to, but not equal to, a browser's Worker class. To ease implementation on our side, we use a library, web-worker, that provides a wrapper around node's worker_threads, which is API-compatible to a browser's `Worker. Any other library that provides the standard Web Worker methods should be fine though. The package is not installed automatically to avoid the unnecessary dependency for everyone who is not interested in using a web worker. A warning is raised if one requests a web worker without having installed the package. elkjs falls back to the non-Web Worker version in that case.

Browser

<html>
  <script src="./elk.bundled.js"></script>
  <script type="text/javascript">
    const elk = new ELK()

    elk.layout(graph)
       .then(function(g) {
         document.body.innerHTML = "<pre>" + JSON.stringify(g, null, " ") + "</pre>"
       })
  </script>
</html>

<html>
  <script src="./elk-api.js"></script> <!-- use elk-api.js here! -->
  <script type="text/javascript">
    const elk = new ELK({
      workerUrl: './elk-worker.js'
    })

    elk.layout(graph)
       .then(function(g) {
         document.body.innerHTML = "<pre>" + JSON.stringify(g, null, " ") + "</pre>"
       })
  </script>
</html>

Typescript

import ELK from 'elkjs/lib/elk.bundled.js'
const elk = new ELK()


import ELK from 'elkjs/lib/elk-api'
const elk = new ELK({
  workerUrl: './elk-worker.min.js'
})

Debugging

For debugging purposes you may want to use the non-minified versions that are available as well. In this case the non-minified webworker version can be configured like so:

const ELK = require('elkjs/lib/elk-api.js')
const elk = new ELK({
    workerFactory: function(url) { // the value of 'url' is irrelevant here
        const { Worker } = require('elkjs/lib/elk-worker.js') // non-minified
        return new Worker(url)
    }
})

API

The elkjs library provides a single object: the ELK. The ELK has a constructor that can be used to construct it:

Apart from that the ELK offers the following methods:

The three methods starting with known basically return information that, in the Java world, would be retrieved from the LayoutMetaDataService.

Logging and Execution Times

(Since 0.6.0)

ELK provides some means to log debug information during layout algorithm execution. The details can be found in the Algorithm Debugging section of ELK's documentation. Not all of it is available in elkjs though, for instance, it is not possible to save intermediate results of the laid out graphs. Furthermore, while internally execution time is measured in nanoseconds on the Java side, in elkjs we have to resort to milliseconds. Note that the returned execution times are in seconds. For small graphs this may often result in execution times being reported as 0.

See below an example call and the example output.

elk.layout(simpleGraph, {
    layoutOptions: {
        'algorithm': 'layered'
    },
    logging: true,
    measureExecutionTime: true
})

{
  "id": "root",
  "children": [ ... ],
  "edges": [ ... ],
  "logging": {
    "name": "Recursive Graph Layout",
    "executionTime": 0.000096,
    "children": [ {
      "name": "Layered layout",
      "logs": [
        "ELK Layered uses the following 17 modules:",
        "   Slot 01: org.eclipse.elk.alg.layered.p1cycles.GreedyCycleBreaker",
            [ ... ]
        "   Slot 16: org.eclipse.elk.alg.layered.intermediate.ReversedEdgeRestorer"
      ],
      "executionTime": 0.000072,
      "children": [ { "name": "Greedy cycle removal", "executionTime": 0.000002 },
                      [ ... ]
                    { "name": "Restoring reversed edges", "executionTime": 0 } ]
    } ]
  }
}

Building

Open in Gitpod

For building, a checkout of the ELK repository is required and should be located in the same directory as the checkout of this repository. Like so:

some_dir/
 ├── elkjs
 └── elk

npm install
npm run build

For a new release, the following version numbers have to be changed:

Afterwards you can find the created files in the lib folder.

Current procedure

git checkout -b releases/0.x.x
# Check that the version numbers are correct, if necessary update versions and commit the changes
npm install
npm run build
npm run test
# Add ./lib/ directory and commit
git tag 0.x.x
# Push release branch and tags to remote
git push --tags --set-upstream origin releases/0.x.x
# Create a new release on Github for the new tag and afterwards publish to npm 
npm publish --tag=latest

Afterwards the following version numbers have to be changed to the next release number:

Incorrect npm tags

Incorrectly tagged versions on npm can be updated with npm dist-tag add elkjs@<version> <latest/next>.

Links

In the following a list of asorted links to other projects and sites that may prove helpful:

Example Users of elkjs

Note: We are happy to extend this list further, so please contact us if you have a project to add

Thanks