Note - This tutorial is outdated. Please see the latest version of Working with ports.
Disclaimer - The following tutorial was created with a past version of JointJS. The tutorial is still provided for those who may face a similar problem, but it may no longer show the best practices of JointJS. You may encounter the following issues:
We now recommend not using
devs shapes as they are maintained for backwards compatibility
reasons only. They could be used if you are not planning to change an individual port's attributes.
Use any other shape with the
Element Port API instead.
Our current recommendations on best practices can be found in the appropriate sections of the basic and intermediate tutorials.
Many diagramming applications deal with elements with ports. Ports are usually displayed as circles inside diagram elements and are used not only as "sticky" points for connected links but they also further structure the linking information. It is common that certain elements have lists of input and output ports. A link might then point not to the element as a whole but to a certain port instead.
JointJS has a built-in support for elements with ports, linking between ports and a facility for defining what connections are allowed and what not. This is useful if you, for example, want to restrict linking in between input ports, or output ports or between a certain port of an element A and a certain port of an element B. This tutorial shows you how you can do all that.
The easiest way to start with elements with ports is using the
joint.shapes.devs plugin. Search
plugin defines one important shape, the
joint.shapes.devs.Model*. You can just instantiate that
outPorts arrays as parameters. You can further set the
coloring of the ports
and label for your element as you can see in the example below. Moreover, JointJS takes care of preparing
the view and the magnets** for
UI interaction. That's why you can already click and drag a port and JointJS automatically creates a link
of that port.
JointJS and the
joint.shapes.devs.Model also makes it easy to change ports. Simply set the
outPorts arrays of your element:
element.set('inPorts', ['newIn1', 'newIn2', 'newIn3']); element.set('outPorts', ['newOut1', 'newOut2']);
*DEVS is an abbreviation for Discrete EVent System specification and is a formalism for modeling and analyzing general systems. This formalism uses two types of models (Atomic and Coupled) both having a set of input and output ports.
**Magnets in JointJS are SVG sub-elements that serve as sticky points for links. If you use the
you don't have to define your magnets yourself, instead the
joint.shapes.devs.Model shape does
it for you.
Now when you have your elements with ports created, you can start observing what port is connected with a link to what other port. This is easy to do thanks to JointJS storing the information about ports in the link models themselves once the links are created via the UI. The following example shows you how you can get the linking information. Try to connect a port of one element to another port of another element.
Now you know how to create elements with ports and how to get the linking information. Another practical
functionality related to elements with ports and their links is restricting certain connections. Say you
links to never start in input ports and never end in output ports. This is the most usual case. However,
all kinds of restrictions are possible and application specific. JointJS doesn't limit you. Instead, it
you to define a function that simply returns
true if a connection between a source magnet of a
and a target magnet of a target element is allowed, and
false otherwise. If the connection is
allowed JointJS does not connect the magnets (and associated ports). Furthermore, you can mark certain
"passive" in which case JointJS treats these magnets in a way that they can never become a
source of a link.
For further information, please see the list of options that you can pass to the
joint.dia.Paper in the API reference page,
especially the two related functions:
To improve user experience little bit you might want to enable the link snapping. While the user is dragging a link, it searches for the closest port in the given radius. Once a suitable port is found (it meets requirements specified in validateConnection()) the link automatically connects to it. You can try this functionality in the example below.
Another way how to make user's life easier can be to offer him all magnets he can connect to while he
is dragging a link. To achieve this you have to enable
markAvailable option on the
paper and add some css rules into your stylesheet like in the example bellow.