Working with Ports (Archive)

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:

Note - 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.

Creating elements with ports

The easiest way to start with elements with ports is using the joint.shapes.devs plugin. Search for joint.shapes.devs.js file. This plugin defines one important shape, the joint.shapes.devs.Model*. You can just instantiate that shape and pass the inPorts and 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 coming out of that port.

JointJS and the joint.shapes.devs.Model also makes it easy to change ports. Simply set the inPorts/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 joint.shapes.devs plugin, 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.


            
            
            
            


            
Linking restrictions


            
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
                want
                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
                allows
                you to define a function that simply returns true if a connection between a source magnet of a
                source element
                and a target magnet of a target element is allowed, and false otherwise. If the connection is
                not
                allowed JointJS does not connect the magnets (and associated ports). Furthermore, you can mark certain
                magnets as
                "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: validateConnection() and validateMagnet().
            


            

            

            
            


            

            
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.


            
            

            


            
Marking available magnets


            
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.