DEMOS
DOCS
FEATURES
DOWNLOAD
PURCHASE
CONTACT
BLOG

Groups

jsPlumb supports the concept of 'Groups', which are elements that act as the parent for a set of child elements. When a Group element is dragged, its child elements (which are, in the DOM, child nodes of the Group element) are dragged along with it. Groups may be collapsed, which causes all of their child elements to be hidden, and for any connections from a child element to outside of the Group to be "proxied" onto the Group's collapsed element.

Adding a Group

To add a Group you first need to have added it as an element in the DOM. Let's assume you have some element called foo. It can be any valid HTML element but since Groups are by their nature containers for other elements it's probably best to just stick to trusty div. So let's assume you have a variable foo that references a DIV element.

A simple example, using the defaults:

jsPlumb.addGroup({
  el:"foo",
  id:"aGroup"
});

Here we've created a Group with ID aGroup. Its element - foo - will be made draggable, and it will also be configured to accept elements being dropped onto it. By default, child elements will be draggable outside of the Group element, but if they are not dropped onto another Group they will revert to their position inside the Group element before they were dragged.

Several aspects of a Group's behaviour can be configured; broadly speaking these fall into two categories: the behaviour of the Group element, and the behaviour of its child elements.

Group element parameters

  • draggable Set to true by default. If false, the Group element will not be made into a draggable element.
  • dragOptions Options for the Group element's drag behaviour. One parameter you will likely want to consider in the dragOptions is filter, which provides a selector, or selectors, identifying elements that should not cause a drag to begin. For a Group element you will probably want to identify the child elements of the Group, so that they can be dragged without kicking off a drag of the Group element.
  • droppable Set to true by default. If false, the Group element will not allow elements to be dropped onto it in order to add them to the Group.
  • dropOptions Options for the Group element's drop behaviour.
  • proxied True by default. Indicates that connections to child elements inside the Group (which emanate from outside of the Group) should be proxied, when the Group is collapsed, by connections attached to the Group's element.

Child element behaviour parameters

  • revert By default this is true, meaning that child elements dropped outside of the Group (and not onto another Group that is accepting droppables) will revert to their last position inside the group on mouseup. If you set revert:false you get a Group that allows child elements to exist outside of the bounds of the Group element, but which will still drag when the Group is dragged and will be made invisible when the Group is collapsed.

  • prune Set to false by default. If true, a child element dropped in whitespace outside of the Group element will be removed from the Group and from the instance of jsPlumb, and any connections attached to the element will also be cleaned up.

  • orphan Set to false by default. If true, a child element dropped in whitespace outside of the Group element will be removed from the Group, but not from the instance of jsPlumb.

  • constrain Set to false by default. If true, child elements are constrained to be dragged inside of the Group element only.

  • ghost Set to false by default. If true, a child element that is dragged outside of the Group element will have its original element left in place, and a 'ghost' element - a clone of the original - substituted, which tracks with the mouse.

  • dropOverride False by default. If true, child elements may be dragged outside of the Group element (assuming no other flag prevents this), but may not be dropped onto other Groups.

Collapsed state

By default, a Group will initially be rendered in its expanded state. You can request the Group be collapsed initially:

jsPlumb.addGroup({
  el:"foo",
  collapsed:true
});

Groups can be removed with the removeGroup method:

jsPlumb.removeGroup("aGroup");

This will remove the Group with ID aGroup. If you also wish to remove all of the Group's child elements you can provide a second argument:

jsPlumb.removeGroup("aGroup", true);

Proxy Endpoints

You can control the location, appearance and behaviour of the Endpoints that appear when a Group is collapsed with the anchor and endpoint parameters. These take the same values as in the other parts of the API in which they appear. For instance, perhaps you want to show a smallish dot that tracks the perimeter of a Group when it is collapsed:

jsPlumb.addGroup({
    el:someElement,
    id:"aGroup",
    anchor:"Continuous",
    endpoint:[ "Dot", { radius:3 } ]
});

Perhaps you want to show a large rectangle in the top left corner:

jsPlumb.addGroup({
    el:someElement,
    id:"aGroup",
    anchor:"TopLeft",
    endpoint:[ "Rectangle", { width:10, height:10 } ]
});

etc. Any valid anchor or endpoint may be used.


Adding an element to a Group

You can add an element to a Group programmatically with the addToGroup(group, el) method:

jsPlumb.addToGroup("aGroup", someElement);

If you try to add an element that already belongs to some other Group an exception is thrown.


Removing an element from a Group

You can remove an element from a Group programmatically with the removeGromGroup(el) method:

jsPlumb.removeFromGroup(someElement);

Note that you do not need to nominate the Group from which you wish to remove the element. Since an element can belong to only one Group at a time, it will simply be removed from the Group. If you call this method with an element that does not belong to a Group, nothing happens.


Dragging and dropping child elements

By default, Groups are configured to accept elements being dropped onto them - any element that is currently being managed by the jsPlumb instance, not just existing members of other groups. There are a few ways to prevent this, both already discussed above:

  • Set droppable:false when you create a Group:
jsPlumb.addGroup({
    el:someElement,
    droppable:false
});

This prevents the Group from accepting dropped elements.

  • Set constrain:true when you create a Group:
jsPlumb.addGroup({
  el:someElement,
  constrain:true
});

This will prevent elements from being dragged outside of the Group.

  • Set dropOverride:true when you create a Group:
jsPlumb.addGroup({
  el:someElement,
  dropOverride:true
});

This will prevent elements from being dropped onto some other Group.


Collapsing and expanding Groups

Use collapseGroup and expandGroup:

jsPlumb.collapseGroup("aGroup");

jsPlumb.expandGroup("aGroup");

CSS

Three CSS classes are used:

ClassPurpose
jtk-group-expandedadded to non-collapsed group elements (added when group initialised)
jtk-group-collapsedadded to collapsed group elements
jtk-ghost-proxyadded to the proxy element used when `ghost` is set to true

Events

A number of events are fired by the various methods for working with Groups.

EventDescriptionParameters
group:add Fired when a new Group is added {group:Group}
group:remove Fired when a Group is removed {group:Group}
group:addMember Fired when an element is added to a Group. If `sourceGroup` is provided, then it indicates the element was previously a member of that group before being added to this group. {group:Group, el:Element, [sourceGroup]:Group}
group:removeMember Fired when an element is removed from a Group. If `targetGroup` is provided, then it indicates the element will be added to that group after having been removed from this one. {group:Group, el:Element, [targetGroup]:Group}
group:collapse Fired when a Group is collapsed {group:Group}
group:expand Fired when a Group is expanded {group:Group}

Miscellaneous Methods

Retrieving a Group

  • getGroup(ID) Return the Group with the given ID. May be null.

Finding out the Group to which an element belongs

  • getGroupFor(elementOrID) - Gets the Group to which the given element (specified as a DOM element or element ID) belongs to. Returns null if the element either does not exist or does not belong to a Group.

Getting the members of a Group

  • getMembers() - Note that this is a method on the Group object, which you either got back from a call to addGroup on a jsPlumb instance, or you retrieved from a jsPlumb instance using getGroup(groupId).