UI / Labels

Labels

A common requirement for interfaces using the Toolkit is the ability to label edges. This is supported by the underlying instance of the Community edition via the concept of Overlays. For instance, here's an edge definition inside a view that has an arrow at its terminus and a label halfway:

views:{
    ... 
    edges:{
        default:{
            overlays:[
                [ "Arrow", { location:1 }],
                [ "Label", { location:0.5, label:"Label Text" }]
            ]
        }
    } 
}

In this example the location of the Label overlay is in fact unnecessary - the default location for all overlays is 0.5.

We see also in the example above that the label text is fixed to "Label Text". Labels can instead extract their value from the data backing the edge on which they reside:

views:{
    ... 
    edges:{
        default:{
            overlays:[
                [ "Arrow", { location:1 }],
                [ "Label", { location:0.5, label:"${label}" }]
            ]
        }
    } 
}

The backing data for this edge could then be:

{
    label:"Label Text"
}

to achieve the same result as before. But of course in this case if you update the edge, using the updateEdge method on an instance of the Toolkit, the label will be changed appropriately.

Since labels are a very common overlay, the Toolkit (since version 1.16.1) supports a shortcut syntax for them:

views:{
    ... 
    edges:{
        default:{
            overlays:[
                [ "Arrow", { location:1 }]                
            ],
            label:"${label}"
        }
    } 
}

Note that here we have used an interpolated value for the label, but hardcoded values are of course also supported.

As mentioned above, the default location for a label (indeed, any overlay) is 0.5. This is a measure of the length of the path traversed by the edge on which the label resides. 0.5 means halfway along this path. If using longhand syntax for a label, location is specified inside the label overlay declaration:

views:{
    ... 
    edges:{
        default:{
            overlays:[
                [ "Arrow", { location:1 }],
                [ "Label", { location:0.2, label:"${label}" }]
            ]
        }
    } 
}

The equivalent declaration using shorthand syntax would be:

views:{
    ... 
    edges:{
        default:{
            overlays:[
                [ "Arrow", { location:1 }]                
            ],
            label:"${label}",
            labelLocation:0.2
        }
    } 
}

labelLocation is the default name for the attribute from which the label's location should be derived, and of course given that it is declared here in the edge definition it is a fixed value. However, it does not need to be declared in the edge definition - it can instead be provided in the edge data:

{
    label:"Label Text",
    labelLocation: 0.2   
}

If you need to, you can change labelLocation to some other attribute, by declaring inside the edge definition what the name of this attribute will be:

views:{
    ... 
    edges:{
        default:{
            overlays:[
                [ "Arrow", { location:1 }]                
            ],
            label:"${label}",
            labelLocationAttribute:"putMyLabelAt"
        }
    } 
}
{
    label:"Label Text",
    putMyLabelAt: 0.2   
}

In version 1.18.1 the ability to drag labels was introduced, via an optional include - jsplumbtoolkit-labels. In this include, the class jsPlumbToolkitLabelDragManager is available.

To import the label drag manager using npm:

"dependencies":{
    
    "jsplumbtoolkit":"file:./jsplumbtoolkit.tgz",
    ...
    "jsplumbtoolkit-labels":"file:./jsplumbtoolkit-labels.tgz",
    ...
    
}

To import the label drag manager directly:

<script type="text/javascript" src="/path/to/jsplumbtoolkit-labels.js"></script>

jsplumbtoolkit-labels.js is available in the dist/js directory of your licensed package. For evaluators and licensees, jsplumbtoolkit-labels-min.js is available in the dist/js directory.

To instantiate a label drag manager:

new jsPlumbToolkitLabelDragManager({
    surface:someSurface
});

  • IMPORTANT If you use the shortcut syntax to set edge labels as discussed above, the Toolkit assigns an ID of "label" to the overlay that is created. The label drag manager currently only operates on the overlay that has this id. If you add a Label overlay yourself in the overlays for some edge type, you need to ensure you set its id to "label":
overlays:[
    [ "Label", { id:"label", label:"Text" }]
]
  • The label drag manager uses the same underlying library that supports dragging throughout the Toolkit to enable dragging on labels.
  • Labels are constrained to the path inscribed by their edge.
  • After a label is dragged, the edge's backing data is updated with the new label location. By default this means that the label drag manager will update the value of labelLocation, but if, as discussed above, you have altered the name of the attribute to write, the label drag manager will use that attribute name instead.
  • An edgeUpdated event will be fired after a label is dragged.