Doka Instance

The Doka instance is the object returned when Doka.create method is used. It's an object linked to a DOM element. The Doka instance can be used to edit an image file.

Properties

The Doka instance exposes the following properties.

Toggle functionality

Output format

Crop configuration

Size configuration

Filter configuration

Color controls configuration

Markup configuration

The markupFontSizeDefault, markupFontFamilyDefault, markupShapeStyleDefault, markupLineStyleDefault, and markupLineDecorationDefault properties have been deprecated as of Doka version 6.0.0.

Sticker configuration

Labels

Callbacks

Hooks

Styles

Events

Doka exposes the following events, they're mostly the same as the callback methods. The event detail property will contain the relevant event information. We can subscribe to them by listing on the root node.

const doka = document.querySelector('.doka--root');
doka.addEventListener('Doka:confirm', (e) => {
    console.log('Image edited', e.detail);
});

Methods

DOM manipulation

Event Methods

Doka provides the on, onOnce and off methods as an alternative way to listen for events. We can listen for the same events but can do so without adding the 'Doka:' prefix. Parameters received by the handler functions are the same as defined on the callback methods.

// 'confirm' instead of 'Doka:confirm'
const doka = Doka.create();
doka.on('confirm', (output) => {
    console.log('Image edited', output);
});

Setting options

To override already set options on a Doka instance we can either use the setOptions method or adjust the properties directly. Updating options might not always result in an update to the editor.

const doka = Doka.create();
doka.setOptions({
    outputQuality: 70,
});

Adjusting individual properties:

const doka = Doka.create();
doka.outputQuality = 70;

Loading an image

To load an image to Doka we can set the src property while initialising or use the edit or open method.

All three options (src, edit(), and load()) accept the following data formats:

• Blobs or File objects
• Local URLs
• DataURLs
• Image or canvas elements

// Load image from a File object or Blob
doka.open(file);

// Load image from a local URL
doka.open('./path/to/selfie.jpeg');

// Load image from a dataURI
doka.open('data:image/png;base64,SGVsbG8sIFdvcmxkIQ...');

// Load image from an image tag
doka.open(document.querySelector('img'));

// Load image from an canvas tag
doka.open(document.querySelector('canvas'));

Both the edit and load method return a Promise.

• The Promise returned by the edit method resolves when the user is done editing.
• The Promise returned by the load method resolves when the image has successfully loaded.

doka.open('./path/to/selfie.jpeg').then((data) => {
    // Called when the source has been loaded to the editor
    // Receives the current editor state
});

doka.edit('./path/to/selfie.jpeg').then((output) => {
    // Called when the source image has been edited
    // Receives the output file and optionally, if `outputData`
    // is set to true, the editor state
});

The second argument to both these methods can be an option object describing the editor state. The following examples will only show the load method as both methods have the same signature.

doka.open('./path/to/selfie.jpeg', {
    crop: {
        center: {
            x: 0.5,
            y: 0.5,
        },
        flip: {
            horizontal: false,
            vertical: false,
        },
        zoom: 1,
        rotation: 0,
        aspectRatio: null,
    },
});

Updating the editor

We can use the setData method to pass new view instructions to the Doka editor. Doka will then update the view accordingly.

The following example sets the zoom level to 2.

doka.setData({
    crop: {
        zoom: 2,
    },
});

An alternative way to update the view is to set a new crop property.

doka.crop = {
    center: {
        x: 0.5,
        y: 0.5,
    },
    flip: {
        horizontal: false,
        vertical: false,
    },
    zoom: 1,
    rotation: 0,
    aspectRatio: 1,
};

Retrieving data from the editor

We can get the current state of the editor using the getData method.

doka.getData().then((output) => {
    // Called when the source image has been edited
    // Receives the output file and optionally, if `outputData`
    // is set to true, the editor state
});

We can override the output contents by supplying an options object to the getData method.

doka.getData({
    file: true,
    data: true
}.then(output => {
    // output will now contain both file and output data
})

Setting crop aspect ratio options

The aspect ratio option dropdown is populated by a list of label, value pairs.

The label is what the text shown in the aspect ratio dropdown, the value is either the aspect ratio to use or the width and height values to use for the given label.

The value can be one of the following:

If the value is set to a size object the aspect ratio is derived from the given width and height.

The snippet below creates a crop options dropdown.

Doka.create({
    cropAspectRatioOptions: [
        {
            label: 'Free',
            value: null,
        },
        {
            label: 'Portrait',
            value: 1.5,
        },
        {
            label: 'Square',
            value: '1:1',
        },
        {
            label: 'Landscape',
            value: 0.75,
        },
    ],
});

This creates a size preset dropdown, in this situation we'd probably also want to change the label of the crop aspect ratio dropdown to something like "presets", we can do this by setting our label text to the labelButtonCropAspectRatio property.

Doka.create({
    cropAspectRatioOptions: [
        {
            label: 'Profile Picture',
            value: {
                width: 180,
                height: 180,
            },
        },
        {
            label: 'Profile Header Image',
            value: {
                width: 1200,
                height: 600,
            },
        },
        {
            label: 'Timeline Photo',
            value: {
                width: 800,
                height: 400,
            },
        },
    ],
});

Setting filters

By default the filters property contains the following filter configuration.

{
    'original': {
        label: 'Original',
        matrix: () => null
    },
    'chrome': {
        label: 'Bright',
        matrix: () => [
            1.398,-0.316, 0.065,-0.273, 0.201,
            -0.051, 1.278,-0.080,-0.273, 0.201,
            -0.051, 0.119, 1.151,-0.290, 0.215,
                0.000, 0.000, 0.000, 1.000, 0.000
        ]
    },
    'fade': {
        label: 'Dark',
        matrix: () => [
            1.073,-0.015, 0.092,-0.115,-0.017,
            0.107, 0.859, 0.184,-0.115,-0.017,
            0.015, 0.077, 1.104,-0.115,-0.017,
            0.000, 0.000, 0.000, 1.000, 0.000
        ]
    },
    'mono': {
        label: 'Mono',
        matrix: () => [
            0.212, 0.715, 0.114, 0.000, 0.000,
            0.212, 0.715, 0.114, 0.000, 0.000,
            0.212, 0.715, 0.114, 0.000, 0.000,
            0.000, 0.000, 0.000, 1.000, 0.000
        ]
    },
    'noir': {
        label: 'Noir',
        matrix: () => [
            0.150, 1.300,-0.250, 0.100,-0.200,
            0.150, 1.300,-0.250, 0.100,-0.200,
            0.150, 1.300,-0.250, 0.100,-0.200,
            0.000, 0.000, 0.000, 1.000, 0.000
        ]
    }
}

Each filter is defined by a key, the internal id of the filter. This key can also be used to select the filter with the filter property.

The filter object has a label and a matrix property. The label value is shown below the filter item in the filters list. The matrix should be set to a function that returns a ColorMatrix (an array with 20 numbers). Read this article on the SVG feColorMatrix filter for more details. Doka does not use the SVG color matrix to create the output image but the matrix format happens to be the same.

You can add additional filters by copying the filter object above.

Doka.create({
    filters: {
        // make sure the original style is in the list
        original: {
            label: 'Original',
            matrix: () => null,
        },

        // the default filters
        chrome: {
            label: 'Bright',
            matrix: () => [
                1.398, -0.316, 0.065, -0.273, 0.201, -0.051, 1.278, -0.08,
                -0.273, 0.201, -0.051, 0.119, 1.151, -0.29, 0.215, 0.0, 0.0,
                0.0, 1.0, 0.0,
            ],
        },
        fade: {
            label: 'Dark',
            matrix: () => [
                1.073, -0.015, 0.092, -0.115, -0.017, 0.107, 0.859, 0.184,
                -0.115, -0.017, 0.015, 0.077, 1.104, -0.115, -0.017, 0.0, 0.0,
                0.0, 1.0, 0.0,
            ],
        },
        mono: {
            label: 'Mono',
            matrix: () => [
                0.212, 0.715, 0.114, 0.0, 0.0, 0.212, 0.715, 0.114, 0.0, 0.0,
                0.212, 0.715, 0.114, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0,
            ],
        },
        noir: {
            label: 'Noir',
            matrix: () => [
                0.15, 1.3, -0.25, 0.1, -0.2, 0.15, 1.3, -0.25, 0.1, -0.2, 0.15,
                1.3, -0.25, 0.1, -0.2, 0.0, 0.0, 0.0, 1.0, 0.0,
            ],
        },

        // add your own filters
        sepia: {
            label: 'Sepia',
            matrix: () => [
                0.394, 0.769, 0.189, 0.0, 0.0, 0.349, 0.686, 0.168, 0.0, 0.0,
                0.272, 0.534, 0.131, 0.0, 0.0, 0.0, 0.0, 0.0, 1.0, 0.0,
            ],
        },
    },
});

Markup Options

Each markup option item is defined as an array.

Color Options

The default selection of colors available to the user.

The color item has 2 to 3 indexes.

1. The name of the color.
2. The value of the color.
3. The value of the color to show in the color palette.

[
    // [ name, color, option color ]
    ['White', '#fff', '#f6f6f6'],
    ['Silver', '#9e9e9e'],
    ['Black', '#000', '#333'],
    ['Red', '#f44336'],
    ['Orange', '#ff9800'],
    ['Yellow', '#ffeb3b'],
    ['Green', '#4caf50'],
    ['Blue', '#2196f3'],
    ['Violet', '#3f51b5'],
    ['Purple', '#9c27b0'],
];

Font Family Options

The default selection of font families available to the user.

The font family item has 2 indexes.

1. The name to show in the dropdown.
2. The CSS font stack.

[
    // [ name, value ]
    ['Serif', "Palatino, 'Times New Roman', serif"],
    ['Sans Serif', 'Helvetica, Arial, Verdana'],
    ['Monospaced', "Monaco, 'Lucida Console', monospaced"],
];

Font Size Options

The default selection of font sizes available to the user.

Each font size item has 2 indexes.

1. The name to show in the dropdown.
2. The relative size to the image.

[
    // name, value
    ['XL', 0.15],
    ['L', 0.125],
    ['M', 0.1],
    ['S', 0.075],
    ['XS', 0.05],
];

Shape Style Options

The default selection of shape styles available to the user.

Each shape style item has 4 indexes.

1. The name to show in the dropdown.
2. The stroke width to use.
3. The stroke style to use (dashed or not).
4. The stroke width to use in the preview icon.

// [ name, stroke width, dash style, option stroke width ]
[
    ['Fill', 0, null, 0],
    ['Outline thick', 0.025, null, 4],
    ['Outline default', 0.015, null, 2],
    ['Outline thin', 0.005, null, 1],
    ['Outline dashed', 0.005, [0.01], 1],
];

Line Style Options

The default selection of line styles available to the user.

Each line style item has 4 indexes.

1. The name to show in the dropdown.
2. The line width to use.
3. The line style to use (dashed or not).
4. The line width to use in the preview icon.

// [ name, line width, dash style, option line width ]
[
    ['Thick', 0.025, null, 4],
    ['Default', 0.015, null, 2],
    ['Thin', 0.005, null, 1],
    ['Dashed', 0.005, [0.01], 1],
];

Line Decoration Options

The default selection of line decorations available to the user.

Each line style item has 4 indexes.

1. The name to show in the dropdown.
2. An array describing the line being and end decorations to use, currently only arrows are supported.

// [ name, decorations ]
[
    ['None', []],
    ['Single arrow', ['arrow-end']],
    ['Double arrow', ['arrow-begin', 'arrow-end']],
];

Adding a Caption to the Image

Using the beforeCreateBlob property we intercept the canvas data before Doka creates the final output file. This is useful when we want to modify the data, for instance, to add a watermark or caption to the image.

The example code below will print Hello World in the top left corner of the image.

Doka.create({
    beforeCreateBlob: (canvas) =>
        new Promise((resolve) => {
            var ctx = canvas.getContext('2d');
            ctx.font = '48px serif';
            ctx.fillText('Hello world', 10, 50);
            resolve(canvas);
        }),
});

Setting The Crop Mask

Using the cropMask settings we can render a mask on top of the crop area. We can define this mask using SVG. SVG has three advantages, one, it's fast, two, it always renders razor sharp, and three, it allows for a lot of flexibility.

You'll notice the cropMask property expects a function. This function receives two arguments. The root element of the mask, and the setInnerHTML function.

We can either choose to define the SVG using the setInnerHTML function or manually build an SVG three using document.createElementNS. In the examples below we'll use the setInnerHTML function.

A Circular Crop Mask

Doka.create({
    cropMask: (root, setInnerHTML) => {
        // This sets the SVG inner HTML
        // 1. It defines a <mask> (white background, black circle on top)
        // 2. Then it fills the screen with transparent white, the mask is applied to this layer
        // 3. Finally it draws a one pixel line around the masked circular area
        setInnerHTML(
            root,
            `
            <mask id="my-mask">
                <rect x="0" y="0" width="100%" height="100%" fill="white"/>
                <circle cx="50%" cy="50%" r="50%" fill="black"/>
            </mask>
            <rect fill="rgba(255,255,255,.3125)" x="0" y="0" width="100%" height="100%" mask="url(#my-mask)"/>
            <circle cx="50%" cy="50%" r="50%" fill="transparent" stroke-width="1" stroke="#fff"/>
        `
        );
    },
});

A Rectangular Bleed Mask

A bleed is used in print to indicate what area of a print might be cut of when the print is sliced.

The bleed can be set using the cropMaskInset property. It's supplied in pixels.

Doka.create({
    // We define a 40 pixel inset for the mask
    cropMaskInset: 40,

    // We supply Doka with the function to render and update the mask
    cropMask: (root, setInnerHTML) => {
        // This sets the SVG inner HTML
        // 1. It defines a <mask> (white background, black rect cutout)
        // 2. Then it fills the screen with transparent white, the mask is applied to this layer
        // 3. Finally it draws a one pixel line around the masked rectangular area
        setInnerHTML(
            root,
            `
            <mask id="my-mask">
                <rect x="0" y="0" width="100%" height="100%" fill="white"/>
                <rect fill="black"/>
            </mask>
            <rect fill="rgba(255,255,255,.3125)" x="0" y="0" width="100%" height="100%" mask="url(#my-mask)"/>
            <rect fill="transparent" stroke-width="1" stroke="rgba(255,255,255,.85)"/>
        `
        );

        // Select the mask element (area that is still visible)
        const bleedMask = root.querySelector('mask rect[fill="black"]');

        // Select the edge element (one pixel white line)
        const bleedEdge = root.querySelector('rect[fill="transparent"]');

        // Return a function that Doka will use to update the mask positions based on the current zoom level
        return (rect) => {
            // update the mask positions
            bleedMask.setAttribute('x', rect.x);
            bleedMask.setAttribute('y', rect.y);
            bleedMask.setAttribute('width', rect.width);
            bleedMask.setAttribute('height', rect.height);

            // update the edge positions, notice the .5s, this is to render sharp 1 pixel wide lines
            bleedEdge.setAttribute('x', Math.round(rect.x) - 0.5);
            bleedEdge.setAttribute('y', Math.round(rect.y) - 0.5);
            bleedEdge.setAttribute('width', rect.width + 0.5);
            bleedEdge.setAttribute('height', rect.height + 0.5);
        };
    },
});

Using an Image as a Mask

Doka.create({
    cropMask: (root, setInnerHTML) => {
        // This sets the SVG inner HTML
        // 1. It simply loads an image that is rendered on top of the crop area
        setInnerHTML(
            root,
            `
            <image xlink:href="mask.png" x="0%" y="0%" width="100%" height="100%"/>
        `
        );
    },
});

Intercepting the output object

The output object returned by Doka can be intercepted modified and returned to Doka right before Doka returns it through its API.

This allows you to do file uploads or further processing while keeping the "Doka is busy" UI in place.

Doka.create({
    outputFile: true,
    afterCreateOutput: (output, setLabel) =>
        new Promise((resolve, reject) => {
            const { file, data } = output;

            // set Doka status to uploading, the `setLabel` call will return a function to update the label progress indicator
            const updateProgress = setLabel('Uploading image…');

            // create a formdata object to send to the server
            const formData = new FormData();
            formData.append('doka', file, file.name);

            // create our request object
            const request = new XMLHttpRequest();
            request.open('POST', 'url/to/upload/location');

            // update the label progress indicator while uploading
            request.upload.onprogress = (e) => {
                updateProgress(e.lengthComputable ? e.loaded / e.total : null);
            };

            // called when the upload was successful
            request.onload = function () {
                if (request.status >= 200 && request.status < 300) {
                    // done! resolve with the output object
                    resolve(output);
                } else {
                    // something went wrong
                    reject('oh no!');
                }
            };

            // start uploading the output image
            request.send(formData);
        }),
});

Adjusting markup hitboxes

beforeMarkupUpdateManipulatorHitbox receives the object below that describes the hitboxes layout.

{ type: 'rect', radius: 22, offset: 5, hideEdges: true, rect: MarkupRect }

Adjust the object to change the position and size of the hitboxes.

radius describes the radius in pixels of each hitboxes. offset describes the offset in pixels from the visual control point towards the outside of the shape. hideEdges is true when the shape is small and edge control points are hidden. rect is the rect of the markup item.

Preview layout mode

With preview layout mode we can render Doka on top of an image. This makes it easier for the user to determine how the image will look in the website once edited.

To get this operational we need to set up the HTML and CSS in a specific way.

First, let's set up the HTML. We'll load the cropped image preview and add a location for the Doka editor to render.

<div class="panel">
    <!-- The current image -->
    <img src="./path/to/selfie.jpeg" />

    <!-- Our editor -->
    <div class="doka"></div>
</div>

/* Position child elements relative to the `.panel` container */
.panel {
    position: relative;
}

/* Scale the image to be the same size as the `.panel` container */
.panel img {
    display: block;
    width: 100%;
}

/* Draw the Doka editor on top of the image. */
.panel .doka--root {
    position: absolute;
    left: 0;
    top: 0;
}

const doka = Doka.create(document.querySelector('.panel .doka'), {

    // Tell Doka to render in preview mode
    styleLayoutMode: 'preview',

    // Tell Doka to also output crop coordinates
    outputData: true,

    // Set crop aspect ratio to the aspect ratio of the preview image.
    // Suppose the preview image size is 800 by 300 pixels, divide
    // height by width to calculate the aspect ratio
    cropAspectRatio: 300 / 800

});

// The crop coordinates of the currently visible image on the page, let's assume it's a slightly of center crop.
const crop = {
    center: {
        x: .5,
        y: .4
    }
}

// Let's now tell Doka to edit the original image and pass the crop coordinates so Doka shows the correct preview.
doka.edit('./path/to/selfie-original.jpeg', { crop })
    .then({ file, data } => {
        // We can now upload the resulting `file` object
        // and/or the crop information contained in the `data` object
    })

Using Stickers

When the sticker util is enabled you can use the stickers property to supply Doka with stickers.

Stickers can be defined in 4 different ways:

• An emoji
• An image source
• A markup object
• A sticker object

See below for an example using multiple sticker types:

Doka.create({
    stickers: [
        // emoji
        '👍',

        // url
        './my-image.jpeg',

        // markup
        ['text', { fontSize: '20px', text: 'Hello World' }],

        // sticker with sole `sticker` property, same as shorthand examples above
        {
            sticker: './my-image.jpeg',
        },

        // sticker with additional `markup` property
        {
            // use this in the sticker list
            sticker: './my-image-thumb.jpeg',

            // use this markup when adding the sticker to the canvas
            markup: './my-image.jpeg',
        },
    ],
});

If the sticker object is used and both sticker and markup props are Markup objects, Doka will merge the sticker and the markup property to create the markup that is added to the canvas.

In the example below the resulting markup will have the "Hello World" text and a fontSize of .5.

Doka.create({
    stickers: [
        {
            // use this in the sticker list
            sticker: ['text', { fontSize: 0.125, text: 'Hello World' }],

            // use this markup when adding the sticker to the canvas
            markup: ['text', { fontSize: 0.5 }],
        },
    ],
});