Overview
The WeaveImageToolAction class that enables users to:
-
Selecting a file and add it to the canvas on a position of its choice.
-
Drag & Drop an Image from the same application to the canvas and add it to the canvas on a position of its choice.
-
Drag & Drop an external Image to the canvas and add it to the canvas on a position of its choice.
-
Copy / pasting an external Image to the canvas.
It provides an intuitive way to add visual content—either by selecting an image file, dragging and dropping, or integrating with an image picker—allowing users to enhance their collaborative workspace with rich media.
Each interaction results in the creation of a WeaveImageNode, which can be resized, moved, and synchronized across all connected users.
The class extends the WeaveAction class.
TypeScript types
type WeaveImageToolActionUploadTypeKeys =
keyof typeof WEAVE_IMAGE_TOOL_UPLOAD_TYPE;
type WeaveImageToolActionUploadType =
(typeof WEAVE_IMAGE_TOOL_UPLOAD_TYPE)[WeaveImageToolActionUploadTypeKeys];
type WeaveImageToolActionStateKeys = keyof typeof WEAVE_IMAGE_TOOL_STATE;
type WeaveImageToolActionState =
(typeof WEAVE_IMAGE_TOOL_STATE)[WeaveImageToolActionStateKeys];
type WeaveImageToolActionOnAddedEvent = {
nodeId: string;
};
type WeaveImageToolActionOnImageUploadedEvent = {
imageURL: string;
nodeId: string;
};
type WeaveImageToolActionOnImageUploadedErrorEvent = {
error: unknown;
};
type WeaveImageToolActionTriggerCommonParams = {
nodeId?: string;
imageId?: string;
options?: ImageOptions;
position?: Konva.Vector2d;
container?: Konva.Layer | Konva.Group;
forceMainContainer?: boolean;
};
type WeaveImageFile = {
file: File;
downscaleRatio: number;
};
type WeaveImageURL = {
url: string;
width: number;
height: number;
};
type WeaveImageToolActionUploadFunction = (
file: File,
imageId: string,
) => Promise<string>;
type WeaveImageToolActionTriggerParams = (
| {
type: typeof WEAVE_IMAGE_TOOL_UPLOAD_TYPE.FILE;
image: WeaveImageFile;
uploadImageFunction: WeaveImageToolActionUploadFunction;
}
| {
type: typeof WEAVE_IMAGE_TOOL_UPLOAD_TYPE.IMAGE_URL;
image: WeaveImageURL;
}
) &
WeaveImageToolActionTriggerCommonParams;
type ImageOptions = {
crossOrigin: ImageCrossOrigin;
};
type WeaveImageToolActionTriggerReturn = {
nodeId: string;
};
type WeaveImageToolDragAndDropProperties = {
imageURL: WeaveImageURL;
} & Omit<WeaveImageToolActionTriggerCommonParams, "position">;
type WeaveImageToolActionConfig = {
style: {
cursor: {
padding: number;
imageThumbnail: {
width: number;
height: number;
shadowColor: string;
shadowBlur: number;
shadowOffset: Konva.Vector2d;
shadowOpacity: number;
};
};
};
};
type WeaveImageToolActionParams = {
config: DeepPartial<WeaveImageToolActionConfig>;
};
type ImageToolActionData = {
props: WeaveElementAttributes;
imageId: string | null;
container: Konva.Layer | Konva.Node | undefined;
imageFile: WeaveImageFile | null;
imageURL: WeaveImageURL | null;
imageFallbackURL: string | null;
forceMainContainer: boolean;
clickPoint: Konva.Vector2d | null;
uploadType: WeaveImageToolActionUploadType | null;
uploadImageFunction: WeaveImageToolActionUploadFunction | null;
};Trigger function params
trigger(cancelAction: () => void, params?: WeaveImageToolActionTriggerParams): WeaveImageToolActionTriggerReturn;For WeaveImageToolActionTriggerParams:
| Property | Type | Required | Description |
|---|---|---|---|
|
|
The type of the upload image, can be 'file' or 'imageURL' |
|
|
|
The metadata of the file image to add, when adding images from a file-picker, on external paste images or when drag-and-drop images from the file-system. If dragging an image that are already uploaded use WeaveImageURL instead. |
|
|
|
An image that will upload the provided file. |
|
|
|
An external Id for the image. It’s saved as imageId prop on the node. |
|
|
|
The options for the HTMLImageElement DOM element. Useful for CORS support. |
|
|
|
Position the image in this coordinates provided by the vector. |
|
|
|
Force the image to be added in the main container and not on the container identified by the pointer. |
When triggering the tool, a WeaveImageToolActionTriggerReturn object is returned, this object contains:
-
nodeId: is the Id of the node added to the canvas.
Drag & Drop from the same application
When you implement drag & drop of an image loaded on a HTMLImageElement that is located on the same application,
on the onDragStart event you must call the setDragAndDropProperties method of the tool and define the following
properties:
-
imageURL: the imageWeaveImageURLmetadata of the image to add. -
imageId: (optional) the image id (external resource id) associated to the image. Used for the image fallback maps normally. -
forceMainContainer: (optional) defines if we should force to add the images on the main stage instead for example A frame.
Then when dropping on the canvas, the image will be added.
Events
onAddingImage
onAddingImage: WeaveImageToolActionOnAddingEvent;The onAddingImage event is called previously the image is added to the canvas, when the user is selecting its position.
onAddedImage
onAddedImage: WeaveImageToolActionOnAddedEvent;The onAddedImage event is called when the image is added to the canvas.