Setting up Doka Image Editor with Angular

For a quick start use the Angular example project included in the product package as a guideline. It includes a normal, modal, and overlay editor example.

Installation on Angular versions 9 and up

We can install doka and angular-doka with npm by copying both of the dependencies to the 'local_modules' folder in the root of our Angular project and running the following command to install them locally.

npm install --save ./local_modules/angular-doka ./local_modules/doka

Please add the path to the Doka Image Editor styles 'local_modules/doka/doka.css' to the build/options/styles array in your angular.json configuration file.

{
    "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
    "version": 1,
    "newProjectRoot": "projects",
    "projects": {
        "angular": {
            "architect": {
                "build": {
                    "options": {
                        "styles": [
                            "src/styles.css",
                            "local_modules/doka/doka.css"
                        ]
                    }
                }
            }
        }
    }
}

Installation on Angular versions 8 and lower

We can install doka and angular-viewengine-doka by copying both folders to a local_modules folder in the Angular project roo.

Please add the path to the Doka Image Editor styles 'local_modules/doka/doka.css' to the build/options/styles array in your angular.json configuration file.

{
    "$schema": "./node_modules/@angular/cli/lib/config/schema.json",
    "version": 1,
    "newProjectRoot": "projects",
    "projects": {
        "angular": {
            "architect": {
                "build": {
                    "options": {
                        "styles": [
                            "src/styles.css",
                            "local_modules/doka/doka.css"
                        ]
                    }
                }
            }
        }
    }
}

Using the components

Now we can import the modules like we normally would and use the Angular <doka-image-editor>, <doka-image-editor-modal>, and <doka-image-editor-overlay> components.

To bind events we can use the Angular event binding syntax.

<doka-image-editor (load)="onLoadImage($event)"></doka-image-editor>

Properties can be used as we would with the normal JavaScript version of the editor but should be assigned to the options attribute. Only src can be supplied with a separate attribute.

<doka-image-editor
    [src]="my-image.jpeg"
    [options]="myOptions"
></doka-image-editor>

Configuring the instance

With the editor logic installed we now need to load the plugins, the locale to use, and set the imageReader which is used to load images. Without these properties the editor won't load.

Doka Image Editor doesn't set any default values or labels, while this helps keep the library size as small as possible, it also means that we have to supply the default values and properties ourselves.

Let's start with registering the plugins using the setPlugins function. We'll then load the locale objects, finally we'll set the imageReader and the default plugin properties.

Registering plugins

Doka Image Editor uses plugins to render each util view. To get started we'll load the crop plugin, the finetune plugin, and the annotate plugin.

<!-- app.component.html -->
<div></div>
// app.module.ts
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';

// import AngularDokaModule
import { AngularDokaModule } from 'angular-doka';

/* 
For Angular version 8 and below use the following import statement instead.

import { AngularDokaModule } from '../../local_modules/angular-doka/angular-doka.module';
*/

@NgModule({
    declarations: [AppComponent],
    imports: [BrowserModule, AngularDokaModule],
    providers: [],
    bootstrap: [AppComponent],
})
export class AppModule {}
// app.component.ts
import { Component } from '@angular/core';
import { DomSanitizer, SafeUrl } from '@angular/platform-browser';

// Import functionalities from `doka`
import {
    // The method used to register the plugins
    setPlugins,

    // The plugins we want to use
    plugin_crop,
    plugin_finetune,
    plugin_annotate,
} from 'doka';

// This registers the plugins with Doka Image Editor
setPlugins(plugin_crop, plugin_finetune, plugin_annotate);

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
})
export class AppComponent {
    constructor(private sanitizer: DomSanitizer) {}
}

Setting the locale object

Now we need to tell Doka Image Editor what labels and icons to use for all its UI controls. To do this we can import the English locale objects and assign them to the locale prop.

The Doka Image Editor module exports a core language file and a language file for each plugin. Currently only the English locale files are available in the package.

You can override the language files to show labels in a different language.

<!-- app.component.html -->
<div>
    <div style="height: 480px">
        <doka-image-editor [options]="options"></doka-image-editor>
    </div>
</div>
// app.module.ts
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';

// import AngularDokaModule
import { AngularDokaModule } from 'angular-doka';

/* 
For Angular version 8 and below use the following import statement instead.

import { AngularDokaModule } from '../../local_modules/angular-doka/angular-doka.module';
*/

@NgModule({
    declarations: [AppComponent],
    imports: [BrowserModule, AngularDokaModule],
    providers: [],
    bootstrap: [AppComponent],
})
export class AppModule {}
// app.component.ts
import { Component } from '@angular/core';
import { DomSanitizer, SafeUrl } from '@angular/platform-browser';

// Import functionalities from `doka`
import {
    // The method used to register the plugins
    setPlugins,

    // The plugins we want to use
    plugin_crop,
    plugin_finetune,
    plugin_annotate,

    // The main UI and plugin locale objects
    locale_en_gb,
    plugin_crop_locale_en_gb,
    plugin_finetune_locale_en_gb,
    plugin_annotate_locale_en_gb,

    // Because we use the annotate plugin we also need
    // to import the markup editor locale
    markup_editor_locale_en_gb,
} from 'doka';

// This registers the plugins with Doka Image Editor
setPlugins(plugin_crop, plugin_finetune, plugin_annotate);

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
})
export class AppComponent {
    constructor(private sanitizer: DomSanitizer) {}

    // editor state
    options: any = {
        // Set locale
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
            ...plugin_finetune_locale_en_gb,
            ...plugin_annotate_locale_en_gb,
            ...markup_editor_locale_en_gb,
        },
    }
}

Changing labels can be done by updating existing locale properties or by creating a custom locale object.

// Merge all the locale objects
const myLocale = {
    ...locale_en_gb,
    ...plugin_crop_locale_en_gb,
    ...plugin_finetune_locale_en_gb,
    ...plugin_annotate_locale_en_gb,
    ...markup_editor_locale_en_gb,
};

// Change label of export button to 'Save'
myLocale.labelButtonExport = 'Save';

Setting the imageReader

The imageReader property expects a list of instructions that tells Doka Image Editor how to load images.

A default image reader is exported by the JavaScript module. It can read resources of type File, Blob, Data URL, URL, HTMLCanvasElement, and HTMLImageElement. It will also automatically correct mobile photo orientation when needed.

By default Doka Image Editor can read images that are supported by the clients browser. In general these image formats are supported by all major browsers.

  • image/gif
  • image/png
  • image/jpeg
  • image/webp
  • image/bmp
  • image/svg

If needed we can use the preprocessImageFile hook to extend the default image reader and load more image formats (for example HEIC).

Let's set the default imageReader property.

<!-- app.component.html -->
<div>
    <div style="height: 480px">
        <doka-image-editor
            [src]="src"
            [options]="options"
            (load)="handleLoad($event)"
        ></doka-image-editor>
    </div>
</div>
// app.module.ts
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';

// import AngularDokaModule
import { AngularDokaModule } from 'angular-doka';
/* 
For Angular version 8 and below use the following import statement instead.

import { AngularDokaModule } from '../../local_modules/angular-doka/angular-doka.module';
*/

@NgModule({
    declarations: [AppComponent],
    imports: [BrowserModule, AngularDokaModule],
    providers: [],
    bootstrap: [AppComponent],
})
export class AppModule {}
// app.component.ts
import { Component } from '@angular/core';
import { DomSanitizer, SafeUrl } from '@angular/platform-browser';

// Import functionalities from `doka`
import {
    // The method used to register the plugins
    setPlugins,

    // The plugins we want to use
    plugin_crop,
    plugin_finetune,
    plugin_annotate,

    // The main UI and plugin locale objects
    locale_en_gb,
    plugin_crop_locale_en_gb,
    plugin_finetune_locale_en_gb,
    plugin_annotate_locale_en_gb,

    // Because we use the annotate plugin we also need
    // to import the markup editor locale
    markup_editor_locale_en_gb,
} from 'doka';

// This registers the plugins with Doka Image Editor
setPlugins(plugin_crop, plugin_finetune, plugin_annotate);

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
})
export class AppComponent {
    constructor(private sanitizer: DomSanitizer) {}

    src: SafeUrl = 'assets/my-image.jpeg';

    handleLoad($event) {
        console.log('load', $event);
    }

    // editor state
    options: any = {
        // Set default imageReader
        imageReader: createDefaultImageReader(),

        // Set locale
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
            ...plugin_finetune_locale_en_gb,
            ...plugin_annotate_locale_en_gb,
            ...markup_editor_locale_en_gb,
        },
    };

}

Doka Image Editor can now load images and render the user interface.

To show the default tools in the annotate view, and the finetune controls in the Finetune plugin we need to import the default properties.

Setting default plugin properties

The controls for the Finetune util as well as the Annotate util are still missing. That's because we have to set these manually.

We need to import markup_editor_defaults because the Annotate plugin uses the Markup Editor. And we import plugin_finetune_defaults to set the default color adjustment controls in the Finetune plugin.

Below we import both and assign the objects to the appendEditor options argument.

<!-- app.component.html -->
<div>
    <div style="height: 480px">
        <doka-image-editor
            [src]="src"
            [options]="options"
            (load)="handleLoad($event)"
        ></doka-image-editor>
    </div>
</div>
// app.module.ts
import { BrowserModule } from '@angular/platform-browser';
import { NgModule } from '@angular/core';

import { AppComponent } from './app.component';

// import AngularDokaModule
import { AngularDokaModule } from 'angular-doka';
/* 
For Angular version 8 and below use the following import statement instead.

import { AngularDokaModule } from '../../local_modules/angular-doka/angular-doka.module';
*/

@NgModule({
    declarations: [AppComponent],
    imports: [BrowserModule, AngularDokaModule],
    providers: [],
    bootstrap: [AppComponent],
})
export class AppModule {}
// app.component.ts
import { Component } from '@angular/core';
import { DomSanitizer, SafeUrl } from '@angular/platform-browser';

// Import functionalities from `doka`
import {
    // The method used to register the plugins
    setPlugins,

    // The plugins we want to use
    plugin_crop,
    plugin_finetune,
    plugin_annotate,

    // The main UI and plugin locale objects
    locale_en_gb,
    plugin_crop_locale_en_gb,
    plugin_finetune_locale_en_gb,
    plugin_annotate_locale_en_gb,

    // Because we use the annotate plugin we also need
    // to import the markup editor locale
    markup_editor_locale_en_gb,

    // Import the default properties
    markup_editor_defaults,
    plugin_finetune_defaults,
} from 'doka';

// This registers the plugins with Doka Image Editor
setPlugins(plugin_crop, plugin_finetune, plugin_annotate);

@Component({
    selector: 'app-root',
    templateUrl: './app.component.html',
    styleUrls: ['./app.component.css'],
})
export class AppComponent {
    constructor(private sanitizer: DomSanitizer) {}

    src: SafeUrl = 'assets/my-image.jpeg';

    handleLoad($event) {
        console.log('load', $event);
    }

    // editor state
    options: any = {

        // Set Markup Editor defaults
        ...markup_editor_defaults,

        // Set Finetune plugin defaults
        ...plugin_finetune_defaults,

        // Set default imageReader
        imageReader: createDefaultImageReader(),

        // Set locale
        locale: {
            ...locale_en_gb,
            ...plugin_crop_locale_en_gb,
            ...plugin_finetune_locale_en_gb,
            ...plugin_annotate_locale_en_gb,
            ...markup_editor_locale_en_gb,
        },
    };

}

Next steps

With the editor set up, we can continue to configure the editor to our liking with the available instance properties