Events

Doka Image Editor exposes a list of events so we can interact and respond to the editor state appropriatly.

Events overview

These are the events fired by the editor instance.

Name Description
'loadstart' Fired when image loading starts.
'loadabort' Fired when image loading is aborted.
'loaderror' Fired when an error is thrown during image load.
'loadprogress' Fired when loading of the image progresses.
'load' Fired when an image has successfully loaded.
'processstart' Fired when processing of an image starts.
'processabort' Fired when processing of an image is aborted.
'processerror' Fired when an error is thrown during image processing.
'processprogress' Fired when processing of the image progresses.
'process' Fired when an image has been processed.
'undo' Fired on undo action.
'redo' Fired on redo action.
'revert' Fired on revert action. Will only be fired wif willRevert resolves with true.
'destroy' Fired when the editor is destroyed.

Instances created with the openEditor JavaScript API fire a couple additional events.

Name Description
'show' Fired when the modal is shown.
'hide' Fired when the modal is hidden.
'close' Fired when the modal is closed using the top left close button.

When using the Shape editor (Used in the Sticker, Annotation, and Decoration plugins) the following additional events are fired.

Name Description
'addshape' Fired when a shape is added, receives added shape.
'selectshape' Fired when a shape is selected, receives selected shape.
'udpateshape' Fired when a shape is updated, receives updated shape.
'removeshape' Fired when a shape is removed, receives removed shape.

Subscribing to events

When using the native version of Doka Image Editor events can be subscribed to using the on method exposed on the Doka Image Editor instance. An altnerative method to subscribe to events is to use the handleEvent property.

If we're using the Custom Elements API we can listen for events using an EventListener.

Events always only return one value which is either passed as a parameter or set as the detail property of the CustomEvent.

// doka instance
editor.on('load', (res) => {
    console.log(res);
    // logs: { src:…, dest:… , size:… }
});

Using handleEvent.

// doka instance
editor.handleEvent = console.log;

// logs: 'loadstart', undefined
// logs: 'loadprogress', { index: 0, task: 'any-to-file', … }
// logs: 'load', { src:…, dest:… , size:… }
// logs: …

Using addEventListener with Custom Elements.

<doka-image-editor src="my-image.jpeg"></doka-image-editor>
<script>
    const editor = document.querySelector('doka-image-editor');
    editor.addEventListener('doka:load', (e) => {
        console.log(e.detail);
        // logs: { src:…, dest:… , size:… }
    });
</script>

Events and JavaScript frameworks

When using one of the included JavaScript framework components listening for events works exactly like you would expect for how components work in your framework of choice.

Please see your preferred framework configuration section for more details.

Editor events

loadstart

Fired when an image starts loading.

loadabort

Fired when the image load is aborted. For example when a new image is set while another image is still loading.

loaderror

Fired when the image load process throws an error.

loadprogress

Fired when the image load process makes progress. Receives the task progress event. The task progress event has the following properties.

Name Description
index The index of the task in the processing array.
task The name of the task in the processing array.
taskProgress The current progress of the task between 0 and 1.
taskLengthComputable Is the length of this task computable, is true when the task length will be updated, the editor will show a progress indicator. If is false the editor will show a spinner.
timeStamp The time stamp of the event.

Each task will fire at least a progress event with taskProgress set to 0 and a progress event with taskProgress set to 1. The 0 progress event will always have taskLengthComputable set to false as the editor doesn't know if the lenght will be computable before the task runs. The taskLengthComputable of the final progress event will either be false or true depening on if progress events were fired.

import { openEditor } from './doka.js';

const doka = openEditor({
    src: './my-image.jpeg',
});

doka.on('loadprogress', console.log);
// logs: { index: 0, task: 'any-to-file' , taskProgress: 0, taskLengthComputable: false, timeStamp: 1614589213257 }

load

Fired when the src image has finished loading, receives the imageReader output object.

import { openEditor } from './doka.js';

const doka = openEditor({
    src: './my-image.jpeg',
});

doka.on('load', console.log);
// logs: { src:…, dest:… , size:… }

processstart

Fired when an image starts processing.

processabort

Fired when image processing is aborted.

processerror

Fired when the image processing process throws an error.

processprogress

Fired when the image processing process makes progress.

process

Fired when the image has finished processing, receives the imageWriter output object.

import { openEditor } from './doka.js';

const doka = openEditor({
    src: './my-image.jpeg',
});

doka.on('process', console.log);
// logs: { src:…, dest:… , imageState:…, store:… }

doka.process();

A list of events that are only used when the editor instance was created with the openEditor method.

show

Fired when the modal is shown.

hide

Fired when the modal is hidden.

close

Fired when the modal is closed using the top left close button.

Shape events

addshape

Fired when a shape is added in the editor.

app.on('addshape', (shape) => {
    console.log('addshape', shape);
    // logs: { /* shape properties */ }
});

selectshape

Fired when a shape is selected in the editor.

app.on('selectshape', (shape) => {
    console.log('selectshape', shape);
    // logs: { /* shape properties */ }
});

udpateshape

Fired when a shape is updated in the editor.

app.on('updateshape', (shape) => {
    console.log('updateshape', shape);
    // logs: { /* shape properties */ }
});

removeshape

Fired when a shape is removed in the editor.

app.on('removeshape', (shape) => {
    console.log('removeshape', shape);
    // logs: { /* shape properties */ }
});