Skip to main content

UI Connectivity

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.

note

This information is applicable when you are using the vanilla Toolkit and when you are using a library integration.

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. A quick example:

<div data-jtk-source="true" data-jtk-target="true"></div>

This is about the most simple example possible: a div element that is declared to be both a source and target of connections established by dragging with the mouse. Note, though, that the surface widget will automatically exclude any elements with a data-jtk-source attribute from being able to instigate dragging, since once an element can act as a connection source it is not possible to also support element dragging: the user's intent would be ambiguous.

So, a more plausible real world scenario would be some element in which only part of it could act as a connection source:

<div data-jtk-target="true">
<h1>Some Vertex</h1>
<div data-jtk-source="true" class="dragFromHere"></div>
</div>

Note that we still put the data-jtk-target attribute on the root element since there is no ambiguity - when the element is behaving as a connection target it is not going to be the element that is currently being dragged.

This is the list of supported connectivity attributes:

  • 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