UI / Basic UI Concepts

Basic UI Concepts

jsPlumb is all about connecting things together. The core abstraction in the jsPlumb Community Edition is the Connection object, which is used by the Toolkit to render an Edge. In the UI, a Connection is broken down into these five concepts:

  • Anchor - a location, relative to an element's origin, at which an Endpoint can exist. You do not create these yourself; you supply hints to jsPlumb, which creates them as needed. They have no visual representation; they are a logical position only. Anchors can be referenced by name, for the Anchors that jsPlumb ships with, or with an array containing various parameters, for greater control. See the Anchors page for more detail.

  • Endpoint - the visual representation of one end of a Connection. In the Community Edition you can create and attach these to elements yourself, which you are required to do to support drag and drop, or have jsPlumb create them when creating a Connection programmatically using jsPlumb.connect(...). You can also join two Endpoints programmatically, by passing them as arguments to jsPlumb.connect(...). See the Endpoints page for more detail.

%toolkit

In the Toolkit edition you specify Endpoints inside the View on a render call on some instance of the Toolkit.

%/toolkit

  • Connector - the visual representation of the line connecting two elements in the page. jsPlumb has four types of these available as defaults - a Bezier curve, a straight line, 'flowchart' connectors and 'state machine' connectors. You do not interact with Connectors; you just specify definitions of them when you need to. See the Connectors page for more detail.

  • Overlay - a UI component that is used to decorate a Connector, such as a Label, Arrow, etc.

  • Group - a group of elements contained within some other element, which can be collapsed, causing connections to all of the Group members to be pooled on the collapsed Group container. For more information, see the Groups page. Both the Toolkit Edition and the Community Edition have the concept of Groups - the Toolkit Edition as part of the data model, using the Community Edition's Group rendering support.

One Connection is made up of two Endpoints, a Connector, and zero or more Overlays working together to join two elements. Each Endpoint has an associated Anchor.


Whenever you need to define a Connector, Endpoint, Anchor or Overlay, you must use a "definition" of it, rather than constructing one directly. This definition can be either a string that nominates the artifact you want to create - see the endpoint parameter here:

{
    ...
    endpoint:"Rectangle"
    ...
}

...or an array consisting of both the artifact's name and the arguments you want to pass to its constructor:

{
    ...
    endpoint:[ "Rectangle", { 
      cssClass:"myEndpoint", 
      width:30, 
      height:10 
    }]
    ...
}

%toolkit

In the Toolkit edition you use these definitions in the view you pass to a render call. Taking the last example here, in the Toolkit Edition we might map it to some edge type:


var common = {
    cssClass:"myCssClass"
};

myToolkitInstance.render({
  ...
  view:{
      ...
      edges:{
          "myEdgeType":{
            anchor:[ "Continuous", { faces:["top","bottom"] }],
            endpoint:[ "Dot", { radius:5, hoverClass:"myEndpointHover" }, common ],
            connector:[ "Bezier", { curviness:100 }, common ],
            overlays: [
              [ "Arrow", { foldback:0.2 }, common ],
              [ "Label", { cssClass:"labelClass" } ]
            ]
          }
      }
  }
})

%/toolkit