🎉 JointJS has new documentation! ðŸ¥³

JointJS+ StackLayoutView

ui.StackLayoutView

ui.StackLayoutView is a view of a stack layout that implements moving elements between stacks, and provides interfaces for changing the default behaviour.

Installation

Include joint.ui.stackLayoutView.js and its dependency joint.layout.stackLayout.js in your HTML:

<script src="joint.layout.stackLayout.js"></script>
<script src="joint.ui.stackLayoutView.js"></script>

Usage

To use stack layout view you need to:

  • Create an object from the layout.StackLayoutView class.
  • Make sure that the elements you want to drag have their interactivity (elementMove) set to false (otherwise an exception is thrown).
  • Every element, which is meant to be involved in the stack layout, should have the stackIndex attribute set (otherwise it will be ignored).

Source Code
const layoutOptions = {
    direction: 'TB',
    topBottom: {
        x: 20,
        y: 20
    },
    stackCount: 4,
    stackSize: 200
};

paper.setInteractivity(false);

const stackLayoutView = new joint.ui.StackLayoutView({
    layoutOptions,
    paper
});

ui.StackLayoutView.API

dragstart(element, x, y) Start a new drag operation with element set as its source.
drag(element, x, y) Drag the source element and display preview of the drop location if any.
dragend(element, x, y) End the drag operation and move the source element to the target stack if there was a valid drop target.
canDrop() Does the current drag operation have a valid drop target? i.e. an element can be moved to a new location.
cancelDrag() Stop the current drag operation.

ui.StackLayoutView.configuration

The following table lists options that you can pass to the ui.StackLayoutView constructor function:

layoutOptions object An object corresponding to layout.StackLayout options.
paper dia.Paper An instance of the paper object.
preview(dragData, stackLayoutView) function A callback function to customize the preview element. It must return an SVGElement object. The preview's position will be set to the middle of the stackSize and to half of the stackElementGap automatically.

The dragData has the following properties:

sourceElement object The element being moved.
sourceStack object The source stack of the source element.
targetStack object The target stack.
insertElementIndex number The index in the target stack to which the element is moved.
invalid boolean Indicates if the current position is invalid (validateMoving returns false).

The plugin also adds the stack-layout-preview class name (and stack-layout-preview-invalid when the drop is invalid) for easy styling.

.stack-layout-preview {
    stroke: #4666E5;
    stroke-width: 3;
}
.stack-layout-preview-invalid {
    stroke: #FF4365;
}

validateMoving(dragData, stackLayoutView) function A predicate, that returns true if the element, which the user interacts with, can be moved to another stack. It defaults to return true;.

The dragData has the following properties:

sourceElement object The element being moved.
sourceStack object The source stack of the source element.
targetStack object The target stack.
insertElementIndex number The index in the target stack to which the element is moved.
canInteract(elementView, stackLayoutView) function A predicate, that returns true if the elementView, which the user interacts with, can be dragged. By default, it returns true for elements with a defined stackIndex attribute.
modifyInsertElementIndex(dragData, point, stackLayoutView) function The value of the insertElementIndex is derived from the pointer position and can be further modified using this callback. The callback is triggered before validation and can be used, for example, to find the nearest valid insert index.

The dragData has the following properties:

sourceElement object The element being moved.
sourceStack object The source stack of the source element.
targetStack object The target stack.
insertElementIndex number The index in the target stack to which the element is moved.

The point is the current pointer coordinates.

When the user drags an element, the plugin creates a copy of the elementView DOM (ghost) and adds the class name stack-layout-ghost (and stack-layout-ghost-invalid if the drop is invalid).

.stack-layout-ghost rect {
    stroke: blue;
}
.stack-layout-ghost-invalid rect {
    stroke: blue;
}

ui.StackLayoutView.model

The StackLayoutView object has the model property that can be used to manipulate elements programmatically. The model has an 'update' event which fires when the layout is updated. The model has following properties:

bbox object A bounding box around elements.
stacks Array<object> The array of stack objects with these properties.
bbox object A bounding box around the stack.
elements Array<object> The array of elements of the stack.
index number The index of the stack inside the layout.
elements Array<object> The array of elements to be laid out (elements with the stackIndex attribute defined).
update() Recalculates the layout manually. Useful when the elements in stacks are changed programmatically.
getStackFromPoint(point) Finds a stack from the point.
getInsertElementIndexFromPoint(stack, point) Finds an insert index in the stack from the point.
getStackFromElement(element) Finds a stack to which the element belongs.
insertElement(element, targetStack, insertElementIndex) Inserts the element in the targetStack at the specified index. It calls update() internally.