Doka Object

The Doka object is the static object available after importing Doka in your project. It exposes the Doka public API which we'll mostly use to add, create, find or destroy Doka instances on the page.

Methods

Properties

Events

The Doka object fires a Doka:loaded event when it's ready. This is useful when we're directly embedding Doka on a page using a defer or async attribute on the <script> tag. In those situations the script will be loaded asynchronously so it might not be available on document ready.

The event detail property will contain the Doka API.

document.addEventListener('Doka:loaded', (e) => {
    console.log('Doka ready for use', e.detail);
});

Creating a Doka instance

Going fullscreen

We can use the create method to create a Doka editor.

Let's create a fullscreen editor.

const doka = Doka.create();

It doesn't do anything yet, because there's no file to edit and we don't want to block the whole viewport with an empty editor.

We can set an initial file using the src property.

const doka = Doka.create({
    src: './path/to/selfie.jpeg',
});

Doka will now automatically open fullscreen and load the image.

Enhancing an HTML element

If we pass an element as the first parameter Doka will replace the element with an editor.

<img src="./path/to/selfie.jpeg" />

<script>
    const doka = Doka.create(document.querySelector('img'));
</script>

This will replace the image with a Doka editor and load the image as its source. By default it will use the image data itself (to save reloading the image from the server).

<style>
    .panel {
        width: 400px;
        height: 600px;
    }
</style>

<div class="panel">
    <img src="./path/to/selfie.jpeg" />
</div>

<script>
    const doka = Doka.create(document.querySelector('img'));
</script>

If we want Doka to load another URL we can add a data-doka-src attribute to the image and Doka will load that instead. This is useful for displaying a low-res or edited version of an image but editing the high res version.

<div class="panel">
    <img
        src="./path/to/selfie.jpeg"
        data-doka-src="./path/to/selfie-original.jpeg"
    />
</div>

<script>
    const doka = Doka.create(document.querySelector('img'));
</script>

Apart from <img> tags Doka can also load <canvas> elements.

<div class="panel">
    <canvas width="400" height="600"></canvas>
</div>

<script>
    const doka = Doka.create(document.querySelector('canvas'));
</script>

To create an empty editor at a given location on the page, pass a <div> as its target. You can then add an image to the editor using the load or edit methods.

<div class="panel">
    <div></div>
</div>

<script>
    const doka = Doka.create(document.querySelector('.panel > div'));
    doka.load('./path/to/selfie.jpeg');
</script>

We can pass properties to the doka instance using data attributes.

Attribute to option mapping is done by removing the data- part, removing dashes and uppercasing each character after a dash. This process turns data-output-width into outputWidth.

It's also possible to pass an additional option object to the create method.

<div class="panel">
    <div data-output-width="400" data-output-height="400"></div>
</div>

<script>
    const dokaTarget = document.querySelector('.panel > div');
    const doka = Doka.create(dokaTarget, {
        outputType: 'image/jpeg',
        outputQuality: 80,
    });

    console.log(pond.outputWidth); // 400
    console.log(pond.outputHeight); // 400
    console.log(doka.outputType); // 'image/jpeg'
    console.log(pond.outputQuality); // 80
</script>

Destroying a Doka instance

Destroying a Doka instance will reset the HTML to its original state.

<img src="./path/to/selfie.jpeg" />

<script>
    const dokaTarget = document.querySelector('img');

    // create the Doka instance
    Doka.create(dokaTarget);

    // destroy the Doka instance by element reference
    Doka.destroy(dokaTarget);
</script>

Automatically Loading Doka Instances

The parse method lets us automatically load Doka elements on the page.

This will look for elements with the class .doka in the subtree of the <body> element.

<img src="./path/to/selfie.jpeg" class="doka" />

<script>
    Doka.parse(document.body);
</script>

Setting Options

We can set default options for all our Doka instances on the page using the setOptions method.

Doka.setOptions({
    labelStatusAwaitingImage: 'Waiting for image…',
    labelStatusLoadImageError: 'Error loading image…',
    labelStatusLoadingImage: 'Loading image…',
    labelStatusProcessingImage: 'Processing image…',
});