Element Dragging
A common feature of interfaces using jsPlumb is that the elements are draggable. You should use the draggable
method on a jsPlumbInstance
to configure this:
myInstanceOfJsPlumb.draggable("elementId");
…because if you don’t, jsPlumb won’t know that an element has been dragged, and it won’t repaint the element.
- Allowed Argument Types
- Required CSS
- Drag Containment
- Dragging Nested Elements
- Dragging Multiple Elements
- Text Selection while dragging
Allowed argument types
draggable
supports several types as argument:
- a String representing an element ID
- an Element
- any “list-like” object whose contents are Strings or Elements.
A “list-like” element is one that exposes a length
property and which can be indexed with brackets ([ ]
). Some examples are:
- arrays
jsPlumbInstance.draggable(["elementOne", "elementTwo"]);
- jQuery selectors
jsPlumbInstance.draggable($(".someClass"));
- NodeLists
var els = document.querySelectorAll(".someClass");
jsPlumbInstance.draggable(els);
Options
TALK ABOUT THE OPTIONS ARG
If you absolutely cannot use jsPlumb.draggable, you will have to arrange to repaint the drag element manually, via jsPlumb.repaint.
Note jsPlumb
is an instance of the jsPlumbInstance
class. If you are working with your own instances of jsPlumb, be sure to call the draggable method on those instances, not the global instance.
Vanilla jsPlumb
In vanilla jsPlumb, drag support is provided by a bundled library called Katavorio. Katavorio supports drag containment and constraining elements to a grid, as well as drag/drop of multiple elements.
Required CSS
You must set position:absolute
on elements that you intend to be draggable. The reasoning for this is that all libraries implement dragging by manipulating the left and top properties of an element’s style attribute.
When you position an element absolute, these left
/top
values are taken to mean with respect to the origin of this element’s offsetParent
, and the offsetParent
is the first ancestor of the element that has position:relative
set on it, or the body if no such ancestor is found.
When you position an element relative, the left
/top
values are taken to mean move the element from its normal position by these amounts, where “normal position” is dependent on document flow. You might have a test case or two in which relative positioning appears to work; for each of these you could create several others where it does not.
You cannot trust relative positioning with dragging, and, despite popular opinion, jQuery’s draggable
method does not “work” with it at all, it just might seem to at times.
Drag Containment
A common request is for the ability to contain the area within which an element may be dragged. This is supported in both jQuery jsPlumb and vanilla jsPlumb (to a certain extent).
jQuery
For jQuery this is as simple as providing a containment parameter:
jsPlumb.draggable($("someSelector"), {
containment:"parent"
});
jQuery and the ‘revert’ option
jQuery offers a revert option that you can use to instruct it to revert a drag under some condition. This is rendered in the UI as an animation that returns the drag object from its current location to wherever it started out. It’s a nice feature.
Unfortunately, the animation that runs the revert does not offer any lifecycle callback methods - no “step”, no “complete”, etc - so it’s not possible for jsPlumb to know that the revert animation is taking place, meaning jsPlumb “doesn’t work”, as it were, with the revert option.
Vanilla
Vanilla jsPlumb offers support for containing a dragged element within the bounds of its parent:
jsPlumb.draggable("someElement", {
containment:true
});
Dragging nested elements
jsPlumb takes nesting into account when handling draggable elements. For example, say you have this markup:
<div id="container">
<div class="childType1"></div>
<div class="childType2"></div>
</div>
…and then you connect one of those child divs to something, and make container draggable:
jsPlumb.connect({
source:$("#container .childType1"),
target:"somewhere else"
});
jsPlumb.draggable("container");
Now when you drag container
, jsPlumb will have noticed that there are nested elements that have Connections, and they will be updated. Note that the order of operations is not important here: if container was already draggable when you connected one of its children to something, you would get the same result.
Nested Element offsets
For performance reasons, jsPlumb caches the offset of each nested element relative to its draggable ancestor. If you make changes to the draggable ancestor that will have resulted in the offset of one or more nested elements changing, you need to tell jsPlumb about it, using the recalculateOffsets
function.
Consider the example from before, but with a change to the markup after initializing everything:
<div id="container">
<div class="header" style="height:20px;background-color:blue;">header</div>
<div class="childType1"></div>
<div class="childType2"></div>
<div>
Connect a child div to some element and make it draggable:
jsPlumb.connect({
source:$("#container .childType1"),
target:"somewhere else"
});
jsPlumb.draggable($(".childType1"));
Now if you manipulate the DOM in such a way that the internal layout of the container node is changed, you need to tell jsPlumb:
$("#container .header").hide(); // hide the header bar. this will alter the offset of the other child elements...
jsPlumb.recalculateOffsets("container"); // tell jsPlumb that the internal dimensions have changed.
// you can also use a selector, eg $("#container")
Note in this example, one of the child divs was made draggable. jsPlumb automatically recalculates internal offsets after dragging stops in that case - you do not need to call it yourself.
Dragging Multiple Elements
Vanilla jsPlumb, because it uses Katavorio as its drag library, supports dragging multiple elements at once. You do this by interacting with the dragSelection
on a given jsPlumb instance. Three methods are provided:
- addToDragSelection: function (spec) Add the specified elements to the drag selection.
- removeFromDragSelection: function (spec) Remove the specified elements from the drag selection
- clearDragSelection Clear the drag selection.
As previously mentioned, these methods are all provided by Katavorio.
Text Selection while dragging
The default browser behaviour on mouse drag is to select elements in the DOM. jQuery suppresses this behaviour, but vanilla jsPlumb does not. To assist with handling this, however, this class is attached to the body at drag start:
_jsPlumb_drag_select
The class is removed at drag end.
A suitable value for this class (this is from the jsPlumb demo pages) is:
._jsPlumb_drag_select * {
-webkit-touch-callout: none;
-webkit-user-select: none;
-khtml-user-select: none;
-moz-user-select: none;
-ms-user-select: none;
user-select: none;
}