Skip to main content

Palette

Provides a palette from which your users can select nodes or groups to add to a canvas. Two modes are supported - the default is to allow users to drag nodes or groups from the palette element onto a canvas using touch/pointer events; it is also possible to run the palette in tap mode, in which a user first selects a node/group in the palette by clicking it, and then subsequently clicks on the canvas where they would like to place a new object of that type.

Usage​

<!doctype html>
<html>
<head>
	<link rel="stylesheet" href="node_modules/@visuallyjs/browser-ui/css/visuallyjs.css">
</head>
  <body>
    <div id="myContainer"></div>
    <div id="myPalette">
        <div data-vjs-type="type1">Type 1</div>
		<div data-vjs-type="groupType1" data-vjs-is-group="true">Group Type 1</div>
    </div>
  </body>
</html>
import { createSurface, Palette } from "@visuallyjs/browser-ui"
    
const renderOptions = { ... }

const surface = createSurface(document.getElementById("myContainer"), renderOptions)
const palette = new Palette(document.getElementById("myPalette"), {
    surface,
    selector:"div"
})

The selector:"div" option tells VisuallyJs what CSS3 selector it should use to determine which child elements of the palette represent draggable items. This selector is simple, but any valid selector will do, so you can use arbitrary markup.

Payloads​

When a user adds a node/group to a canvas from a Palette, VisuallyJs will prepare an initial payload for the new object in one of two ways:

Default extractor​

By default, any data-vjs-*** attribute on the element in the Palette will have its value read and inserted into the payload. For instance, the attribute data-vjs-label="hello" will result in {label:"hello"}.

Custom extractor​

If you provide a dataGenerator, you can control on a fine-grained level what the payload for new objects will be. This is a DataGeneratorFunction whose type definition is:

Marking groups​

To inform VisuallyJs that a certain element represents a Group and not a Node, set data-vjs-is-group="true" on it:

<div>
  <div data-vjs-type="foo">Foo NODE</div>
  <div data-vjs-type="bar" data-vjs-is-group="true">Bar GROUP</div>
</div>

Options​

PaletteOptions
Options for a Palette
NameTypeDescription
allowClickToAdd?booleanWhen in draw mode, allow addition of new vertices simply by clicking, instead of requiring a shape be drawn. (When this is true, the drag to draw functionality also still works)
allowDropOnCanvas?booleanDefaults to true. Allows items to be dropped onto whitespace.
allowDropOnEdge?boolean | CanDropOnEdgeFilterDefaults to false. Allows items to be dropped onto edges in the canvas. A drop on an edge causes that edge to be split, with one edge having the new vertex as a target, and another edge with the new vertex as source.
allowDropOnGroup?booleanDefaults to true. Allows items to be dropped onto groups in the canvas.
allowDropOnNode?booleanDefaults to false. Allows items to be dropped onto nodes in the canvas. If this is true and an element is dropped onto a node, the result is the same as if the element has been dropped onto whitespace. Note that when this is false and the user has dragged something over a node, the drag item is still not considered to be over the canvas, and releasing the mouse button at that time will not cause a new node to be added. Use ignoreDropOnNode if that's the behaviour you want.
allowRotation?booleanWhether or not to allow rotation of elements being dragged. Defaults to true.
autoEdgeConnect?boolean | AutoEdgeConnectOptionsControls whether the palette will automatically connect a new vertex being dragged onto the canvas to existing vertices, if the shape definitions for the new vertex and/or the existing vertices have source/target elements. You can set this to simply 'true', and use defaults, or you can provide values for various options.
canDrop?(candidate:Node | Group, target:Node | Group, onCanvas:boolean) => booleanOptional function that is invoked at the start of a drag, and which identifies allowed drop targets. Each target - the canvas, nodes and groups - is passed in turn to this method; returning false indicates that the given target is not valid for that drag.
canvasDropFilter?CanvasDropFilterOptional function that you can use to inform the Palette that drop should be aborted. This method is invoked at the start of a drag (in drag mode) or when an item is tapped (in tap/draw mode) and is passed the candidate drag object's data.
clickToAddOnly?booleanThis flag relates to "draw" mode, and defaults to false. When true, the palette only supports click to draw new vertices, not drag. This flag is forced to true if the associated UI does not have useModelForSizes set, since there is no point in allowing a user to drag a vertex to some size if its not going to be honoured. When you set this flag and associated UI does have useModelForSizes set, the palette will use default sizes for new nodes/groups.
contentTemplate?stringOptional template that will be used in conjunction with data to generate the HTML content of the palette. The template can return any number of elements (ie. you're not limited to just a single root node)
data?ObjectDataOptional data that will be used in conjunction with contentTemplate to generate the HTML content of the palette.
dataGenerator?DataGeneratorFunctionOptional function to generate an initial payload from an element that has started to be dragged/has been tapped.
dragActiveClass?stringClass to set on the UI canvas and any other drop targets when a new element is being dragged
dragElementClass?stringClass to set on an element being dragged.
dragHoverCannotDropClass?stringClass to set on the UI canvas and any other drop targets when a drag element is hovering over it but drop is not allowed.s
dragHoverClass?stringClass to set on the UI canvas and any other drop targets when a drag element is hovering over it.
dragSize?SizeOptional size to use for elements dragged from the palette; used in drag mode only.
dragSizeGenerator?(payload:ObjectData, el:BrowserElement) => SizeOptional function to generate the size to use for some object that is being dragged.
edgeDropHandler?(newVertex:Vertex, originalEdge:Edge) => EdgeDropInfoIf allowDropOnEdge is true, this function can be provided, to customise the behaviour of the drop. By default, the new vertex is used as the target of the original edge and the source of the new edge. But you might want to connect to ports on the new vertex, and this method allows you to do that: you can return the ID of a port to use for the existing edge's target, a port ID to use for the new edge's source, a source anchor or a target anchor.
elementGenerator?(el:BrowserElement, e:MouseEvent) => BrowserElementOptional function you can provide which will be used to generate an element to use for dragging. The default behaviour is to use a clone of the element the user began dragging, but if you provide this method you can customise that.
enabled?booleanDefaults to true. Set to false if you wish to instantiate the Palette in a disabled state
groupIdentifier?GroupIdentifierFunctionOptional function to use to determine if the element being dragged/has been tapped represents a group. If you do not provide this, the default behaviour is to check for the presence of a data-vjs-is-group attribute on the element, with a value of true.
ignoreDropOnNode?booleanDefaults to false. When true, the palette treats nodes as if they are part of the canvas - a user can drag new items on top of existing nodes and the new item will be added to the canvas. If you want to force your users to drop on canvas whitespace, don't set this. Note that this flag will force allowDropOnNode to false.
ignoreGrid?booleanDefaults to false. By default this class will conform to any grid in place in the surface to which it is attached when dragging items around.
ignoreZoom?booleanBy default, the Palette will apply a scale transform to elements that are being dragged so that they appear at the same size as the UI they're being dragged to. Setting this flag to true will switch off that behaviour.
lassoClass?stringWhen in 'draw' mode, you can optionally provide a class to set on the lasso used by the vertex drawing plugin.
mode?PaletteModeMode to operate in - 'drag', 'tap' or 'draw'. Defaults to 'drag'.
onDrag?DragFunctionOptional function to invoke as the user is dragging a new element, or has tapped an element and is moving the mouse over the canvas.
onVertexAdded?OnVertexAddedCallbackOptional callback that will be invoked after a new vertex has been dropped and added to the dataset.
rotationSpeed?numberThe number of milliseconds required to complete a full rotation of an element when the trigger key is held down. Defaults to 2000.
selectAfterAdd?booleanDefaults to false. When true, a newly added vertex is set as the model's current selection.
selector?stringA CSS selector identifying children of source that are draggable/can be tapped. If not provided, the Palette will use [data-vjs-type].
sourceBrowserElementThe element containing things that will be dragged/tapped.
typeGenerator?TypeGeneratorFunctionOptional function to determine the type of the data object from an element that is being dragged (in drag mode) or has been tapped (in draw/tap mode)
vertexPreviewGenerator?(objectType:string, type:string, data:ObjectData, p:PointXY, e:MouseEvent) => BrowserElementWhen in draw mode, this function can be used to provide the element shown to the user as a new vertex is being drawn.
vertexPreviewUpdater?(el:BrowserElement, origin:PointXY, size:Size, data:ObjectData) => anyWhen in draw mode this function is repeatedly called as the mouse is dragging a new shape. It provides a hook for you to update the element's appearance. This is only called if you provided a vertexPreviewGenerator and it has returned a valid DOM element at the start of a drag.