Community Edition 4.x Beta Release Community Edition 4.x Beta Release
20 Jun 2020
World Cup 2018, Part 2 World Cup 2018, Part 2
26 Jun 2018
World Cup 2018, Part 1 World Cup 2018, Part 1
25 Jun 2018
Community Edition 2.2.2 Release Community Edition 2.2.2 Release
20 Oct 2016
Connecting SVG Shapes (Raphael, Highcharts etc) (update) Connecting SVG Shapes (Raphael, Highcharts etc) (update)
20 Oct 2016
Writing a Layout Decorator Writing a Layout Decorator
25 Jul 2015
Toolkit Edition 1.0.0 Toolkit Edition 1.0.0
23 Jul 2015
Community Edition 1.7.6 Community Edition 1.7.6
23 Jul 2015
Connecting SVG Shapes (Raphael, Highcharts etc) Connecting SVG Shapes (Raphael, Highcharts etc)
22 Jul 2015
The beforeDrag Interceptor The beforeDrag Interceptor
15 Jan 2015
Integrating Jekyll and YUIDoc Integrating Jekyll and YUIDoc
28 Jan 2014
Dragging Multiple Elements Dragging Multiple Elements
17 Jan 2014
Custom Connectors Custom Connectors
22 Dec 2013

Community Edition 4.x Beta Release

Over the last few months, the jsPlumb Community Edition has been ported from Javascript to Typescript, and we're pleased to announce that the first RC from this process is now available for use. There are a few breaking changes to the API in 4.x - although no loss of functionality - and so we decided to change the package name for 4.x, in order to avoid people accidentally upgrading to this new version and finding their code is broken.

As of right now the current 4.x version is 4.0.0-RC1. You can install it via:

npm install @jsplumb/community

..and it's on the branch dev/4.x on Github. The code is still somewhat in flux (you'll probably find an any reference or two if you poke around in it) but the API is largely stable, and even if it changes a little there will be no functionality removed.

We encourage you to give it a try, since the more people use it, the quicker we'll find any bugs that might have been introduced. If you do find an issue, kindly report it on Github, using the 4.x-alpha tag.

Changes in 4.x

Aside from the rewrite in Typescript, there are a few fundamental changes to the internals in 4.x:

  • The code that handles rendering of connections has been extracted from the core and moved into a package that "knows about" the DOM, and now the core code doesn't know about the DOM anymore. To be fair, jsPlumb's internals were always reasonably well abstracted into different areas of concern, but with 4.x this has been extended, and now the code is better placed to support alternative renderers. What does that mean, "alternative renderers" ? Well, consider how currently jsPlumb connects DOM elements with individual SVG elements: this is nice, it gives you the ability to put arbitrary content into the DOM elements and make them more interactive than just a box, but also it can result in a lot of DOM elements when you've got lots of nodes/edges, which can slow things down. And maybe you don't even want an interactive DOM element? Maybe you do just want a box. In that case perhaps a renderer that consisted of a single SVG element would be better for you. With 4.x it will be easier to do this sort of stuff.

  • Element dragging is now handled by a single delegating event handler on the container, rather than configuring each element as a separate draggable. This has vast benefits in terms of both rendering speed and also memory usage.

  • Events such as connection click, element hover, etc, are all also now handled by a single delegating event handler. This has the same benefits as the updates to dragging: improved rendering speed and reduced memory usage.

At the bottom of this post is included the full changelog.

What does this mean for the 2.x branch of the Community Edition?

It means it's got one foot in maintenance mode, basically. It's still used, for now, by the Toolkit Edition (see below), and until there's been a decent uptake of 4.x it would be churlish of us to abandon it anyway. But of course we don't want to maintain two different branches forever, so if you're just starting out with the jsPlumb Community Edition we'd encourage you to use 4.x.

What does this mean for the Toolkit Edition?

Right now, there's no change to the Toolkit Edition. We're working behind the scenes to make a corresponding 4.x release of the Toolkit Edition, also written with Typescript, and using Community Edition 4.x under the hood.

Once we've finished 4.x, some of the benefits for the Toolkit Edition will be:

  • Licensees will be able to take advantage of tree shaking to only include the bits of the Toolkit they need
  • There are performance gains to be had from switching to delegated event handlers
  • We'll be looking into writing a "single svg" renderer, as well as the possibility of supporting React Native
  • The rewrite of the internals of the Toolkit has introduced a plugin mechanism to the Surface, allowing you to write your own, and also meaning that you don't need to include the code for any plugins you're not using.

Changelog

This is the full list of changes in 4.x.

Breaking changes

Methods

  • The empty method was removed from JsPlumbInstance.

  • The deleteEveryEndpoint method was removed from JsPlumbInstance. Functionally, it was identical to reset. Use reset.

  • addEndpoint does not support a list of elements as the first argument - only a single DOM element is supported.

  • makeSource does not support a list of elements as the first argument - only a single DOM element is supported.

  • makeTarget does not support a list of elements as the first argument - only a single DOM element is supported.

  • getWidth and getHeight methods removed from JsPlumbInstance. All they did was return the offsetWidth and offsetHeight of an element.

  • updateClasses method removed from JsPlumbInstance. It was an attempt at keeping reflows to a minimum but was used only in one method internally, which is a method that was very rarely called.

  • setClass method removed from JsPlumbInstance. This brings JsPlumbInstance into line with the way the DOM works: classList offers methods to add/remove/toggle classes, but not to set one particular class.

  • jsPlumbUtil is no longer a static member on the window. Some of its more useful methods for users of the library have been exposed elsewhere:

    • The uuid method, which we use a lot in our demos, and internally, is now exposed on the JsPlumbInstance class and on the global jsPlumb object

    • The extend method is now exposed on the JsPlumbInstance class and on the global jsPlumb object

    • The consume method is exposed on the BrowserJsPlumbInstance class (which is currently the only concrete instance of JsPlumbInstance and the class you will get from a jsPlumb.newInstance(..) call).

  • setId no longer supports an array-like argument. You must now pass in a single id, or element.

  • appendToRoot method removed. If you're using this, use document.body.appendChild(..) instead.

Configuration

  • All defaults converted to camelCase instead of having a leading capital, eg. "Anchors" -> "anchors", "ConnectionsDetachable" -> "connectionsDetachable". This brings the defaults into line with the parameters used in method calls like connect and addEndpoint etc.

  • It is imperative that you provide the container for an instance of jsPlumb. We no longer infer the container from the offsetParent of the first element to which an Endpoint is added. If you do not provide container an Error is thrown.

  • connector-pointer-events not supported on Endpoint definitions. Use cssClass and CSS tricks.

  • labelStyle is no longer supported. Use cssClass and CSS tricks.

  • The LogEnabled and DoNotThrowErrors defaults have been removed.

  • Paint styles for connectors dont support gradients anymore. You can use CSS for this.

  • Removed overlays default. Use connectionOverlays or endpointOverlays now: not all overlay types are supported by Endpoints, so having a common set of overlays doesn't make sense.

CSS classes

  • The jtk-endpoint-anchor css class is not added to endpoints when the associated anchor did not declare a class. It is stillused when the anchor has declared a class (eg jtk-endpoint-anchor-foo), but otherwise it is not added. Without the anchor's class suffix jtk-endpoint-anchor was just a shadow of jtk-endpoint - use jtk-endpoint instead.

  • Managed elements do not have the jtk-managed class applied. They now have a jtk-managed attribute set on them. It is unlikely anyone was using this class but we include it here for completeness.

  • Elements configured via makeTarget do not get assigned a jtk-droppable css class now. Instead, they are given a jtk-target attribute, as well as ajtk-scope-** attribute for every scope that is assigned.

Events

  • The manageElement and unmanageElement events are no longer fired by the jsPlumbInstance class. These were undocumented anyway, but we're calling it out in case you have code that used them.

  • Added drag:start, drag:move and drag:stop events. These replace the start, drag and stop event handlers that used to be supported on individual draggable(..) method calls.

Behaviour

  • By default, every node is draggable. .draggable(someElement) no longer exists. You can make an element not draggable by setting a jtk-not-draggable attribute on it. It doesn't matter what the value of the attribute is, just its presence is all that is required.

  • It is not possible to subclass Connection or Endpoint to provide your own implementations in 4.x.

  • There is no Image endpoint in 4.x. You can achieve this via a Blank endpoint with a css class. Or if you find you cannot and you can't think of any alternative, we could possibly add a Custom endpoint type, with which you could achieve this.

New Functionality

  • elementsDraggable added to Defaults, with a default value of true.

  • Added drag:start, drag:move and drag:stop events to the JsPlumbInstance class. These replace the start, drag and stop event handlers that used to be supported on individual draggable(..) method calls.

  • The Mottle library, which used to be a separate project, has now been incorporated into jsPlumb. For convenience, we have exposed Mottle on the browser window, as some people do use standalone instances of Mottle from time to time.

  • The Katavorio library, which used to be a separate project, has now been incorporated into jsPlumb. At present there is nothing exposed on the window as we did with Mottle, but there could be.