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. Groups may contain other groups; there is no limit to the depth that groups can be nested.

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 myElement that references a DIV element.

A simple example, using the defaults:

instance.addGroup({  el:myElement,  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 constructor parameters#

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.
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.
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 mouse up. 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 By default, a group will initially be rendered in its expanded state. You can request the group be collapsed initially via collapsed:true.
anchor Optional spec to use for the anchor for endpoints used when the group has proxy connections. See discussion below.
endpoint Optional spec to use for the endpoints when the group has proxy connections. See discussion below.

Removing a group#

Groups can be removed with the removeGroup method:

instance.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:

instance.removeGroup("aGroup", true)

When a group is removed but its child members are not, the child members are repositioned so that they are in the same place relative to the container origin that they were in prior to the group removal.

Collapsing and expanding Groups#

Use collapseGroup and expandGroup:


instance.collapseGroup(aGroup)
instance.expandGroup(aGroup)

When you collapse a group, all connections to elements contained within the group are relocated ("proxied") to the group element. This behaviour can be overridden by setting proxied:false when you create a group, in which case all child element connections are simply hidden whenever the group is collapsed.

Also when you collapse a group, jsPlumb writes a CSS class see below to the group's element.

note

jsPlumb does not itself hide child elements when a group is collapsed. It is up to you to do this. See the CSS discussion below for an example

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:

instance.addGroup({    el:someElement,    id:"aGroup",    anchor:"Continuous",    endpoint:{ type:"Dot", options:{ radius:3 } }})

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

instance.addGroup({    el:someElement,    id:"aGroup",    anchor:"TopLeft",    endpoint:{ type:"Rectangle", options:{ 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:

instance.addToGroup(aGroup, someElement)

someElement can represent either a plain element or itself be the container for another group - groups can be nested, to an arbitrary depth, limited only by your good taste in UX.

Removing an element from a group#

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

instance.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 that 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:

instance.addGroup({    el:someElement,    droppable:false});

This prevents the Group from accepting dropped elements.

Set constrain:true when you create a group:

instance.addGroup({  el:someElement,  constrain:true});

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

Set dropOverride:true when you create a group:

instance.addGroup({  el:someElement,  dropOverride:true});

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

CSS#

Three CSS classes are used:

Class	Purpose
jtk-group-expanded	added to non-collapsed group elements (added when group initialised)
jtk-group-collapsed	added to collapsed group elements
jtk-ghost-proxy	added to the proxy element used when `ghost` is set to true

Hiding child elements of a collapsed group#

As mentioned above, jsPlumb does not do this automatically. A simple rule you can include in your CSS to achieve this is:

.jtk-group-collapsed [data-jtk-managed] {    display:none;}

This works because data-jtk-managed is the attribute that jsPlumb writes onto every element it is managing.

Events#

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

Event	Description	Parameters
group:add	Fired when a new Group is added	{group:UIGroup}
group:remove	Fired when a Group is removed	{group:UIGroup}
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?UI: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?:UIGroup}
group:collapse	Fired when a Group is collapsed	{group:UIGroup}
group:expand	Fired when a Group is expanded	{group:UIGroup}

Miscellaneous Methods#

Retrieving a group#

getGroup(id:string) Return the group with the given ID. May be null.

Finding out the group to which an element belongs#

getGroupFor(element:Element) - Gets the group to which the given element belongs to. Returns null if the element either does not exist or does not belong to a group.

Getting the members of a group#

getChildren - 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).