Skip to main content

UI Connectivity#

Note: if you are migrating from version 2.x you may wish to also take a look at the templating migration docs.

Connectivity is declared in your templates by specifying some part of the each vertex's DOM element that can act as a connection source and/or target. This can be via a set of data-jtk-*** attributes, or with one or more <jtk-endpoint ../> elements - or a combination of both of these approaches.

Source and target attributes#

You can specify parts of your UI that should act as connection sources and/or targets using a set of data-jtk- attributes. We'll summarise them first and then provide examples below.

This functionality is new in version 5.x, and replaces the jtk-source and jtk-target elements from 2.x, which are no longer supported. This approach, using attributes to markup your elements, allows you a more fine-grained control over how connectivity is configured, and also allows the Toolkit to use delegated mouse event handlers to support the connectivity. Removing the need to post-process, and attach specific event handlers to, each rendered element provides benefits in both speed of execution and memory usage.

  • data-jtk-source="true" When present, indicates that the given element acts as a source for connections dragged with the mouse. Any element with this attribute set will automatically be excluded from instigating a drag of the vertex on which the element resides.

  • data-jtk-target="true" When present, indicates that the given element acts as a target for connections dragged with the mouse. Elements with this attribute set are not excluded from instigating a drag of the vertex on which the element resides.

  • data-jtk-port-id="portId" This attribute indicates the ID of the logical port that the element represents. A "logical" port is one which exists in the data model, but connections to/from the port in the UI are shown as being attached to the vertex to which the port belongs. Don't confuse this with the data-jtk-port attribute. When you drag a connection to/from some DOM element with this attribute set, you are instructing the Toolkit to associate the source/target of the new edge with a port with the specified ID, but that the edge should be connected visually to the DOM element representing the vertex.

  • data-jtk-port="portId" This attribute indicates that the given element is the specific DOM element to which connections for the given port should be attached. It is distinct from data-jtk-port-id in that this attribute is a "physical" presence of a port. Connections to/from the associated port are attached to this DOM element, and not to the element representing the vertex to which the port belongs.

  • data-jtk-endpoint="true" Indicates that the given element should have an Endpoint created, at render time, as opposed to the element itself behaving as the drag source/target. You can use this in conjunction with data-jtk-port to create an endpoint that is tied to a port. Without the presence of data-jtk-port, the endpoint is considered to represent the vertex.

Advanced usage#

The previous section lists the most commonly used attributes, but there are several more that can be used in more advanced configurations.

  • data-jtk-source-port-id Indicates the ID of the logical port that the element represents when it is acting as an edge source. In some situations you might want to use the same element as a source and target, but have the data model use different logical ports.

  • data-jtk-target-port-id Indicates the ID of the logical port that the element represents when it is acting as an edge target.

  • data-jtk-source-port Indicates the ID of the physical port that the element represents when it is acting as an edge source. In some situations you might want to use the same element as a source and target, but have the data model use different ports ids.

  • data-jtk-target-port Indicates the ID of the port that the element represents when it is acting as an edge target.

  • data-jtk-source-port-type Indicates the type of the port that the element represents when it is acting as an edge source. In some situations you might want to use the same element as a source and target, but have the data model use different ports types.

  • data-jtk-target-port-type Indicates the type of the port that the element represents when it is acting as an edge target.

  • data-jtk-anchor-x="0.75" Only valid when data-jtk-endpoint="true" is set. Fixes the x location of the anchor for the endpoint on the element. The value is a proportional value of travel along the given axis: a value of 0.75 means three quarters of the way along, for instance.

  • data-jtk-anchor-y="0.23432" Only valid when data-jtk-endpoint="true" is set. Fixes the y location of the anchor for the endpoint on the element.

  • data-jtk-anchor-orientation-x="..." Sets the orientation for the given anchor in the X axis. The orientation of an anchor defines the initial direction in which an edge attached to the associated endpoint should travel. Valid values for this attribute are "0" - no preference - or "1" - travel in the X direction.

  • data-jtk-anchor-orientation-y="..." Sets the orientation for the given anchor in the Y axis. The orientation of an anchor defines the initial direction in which an edge attached to the associated endpoint should travel. Valid values for this attribute are "0" - no preference - or "1" - travel in the Y direction.

  • data-jtk-anchor-offset-x="..." Sets the optional offset, in absolute pixels, of the anchor in the X axis from the value computed by its location. The default for this is 0.

  • data-jtk-anchor-offset-y="..." Sets the optional offset, in absolute pixels, of the anchor in the Y axis from the value computed by its location. The default for this is 0.


Specifying endpoints with an element#

You can use the <jtk-endpoint> element to define endpoints inside your templates:

<div>    <jtk-endpoint data-jtk-port="aPortId"                   data-jtk-port-type="foo"                   data-jtk-anchor-x="0.25"                   data-jtk-anchor-y="1"/>                      <jtk-endpoint data-jtk-port="anotherPortId"                   data-jtk-port-type="bar"                   data-jtk-anchor-x="0.75"                   data-jtk-anchor-y="1"/></div>

Valid attribute values on the <jtk-endpoint> element are any of the attributes given above, with the exception of data-jtk-endpoint="true", because this attribute is of course implicitly true on the <jtk-endpoint> element - it indicates the same thing.

These two attributes, on a <jtk-endpoint> element, will set, respectively, the source and target values in the options for the endpoint that is created. You can use these as a shortcut rather than having to map a port type:

  • data-jtk-source="true" This attribute is used to declare that a DOM element is a drag source
  • data-jtk-target="true" This attribute is used to declare that a DOM element is a drag target