There are a few breaking changes when migrating to v6 from older versions.
CoreControls.js is no longer dependent on jQuery, thus all APIs that use jQuery are changed.
The jQuery e isn't passed to event handlers as the first argument anymore. The imported property for annotationChanged is now accessible on the third argument.
JavaScript
1// Version 5.x and older
2docViewer.on('zoomUpdated', (e, zoom) => {
3 ...
4});
5annotManager.on('annotationChanged', (e, annotations, action) => {
6 if (e.imported) {
7 ...
8 }
9});
10
11// Version 6.0 and after
12docViewer.on('zoomUpdated', zoom => {
13 ...
14});
15annotManager.on('annotationChanged', (annotations, action, info) => {
16 if (info.imported) {
17 ...
18 }
19});
Since the event handler now takes an info object as a third argument, it should be also included when manually triggering an annotationChanged event.
JavaScript
1const annotations = [...];
2const action = 'add';
3
4// Version 5.x and older
5annotManager.trigger('annotationChanged', [annotations, action]);
6
7// Version 6.0 and after
8const info = {
9 imported: false, // optional property
10 isUndoRedo: false, // optional property
11};
12
13annotManager.trigger('annotationChanged', [annotations, action, info]);
The innerElement of all widget annotations is now a normal DOM element instead of a jQuery wrapped element. This means that createInnerElement should return a normal DOM element now.
JavaScript
1// Version 5.x and older
2Annotation.SignatureWidgetAnnotation.prototype.createInnerElement = function() {
3 const div = document.createElement('div');
4
5 ...
6
7 return $(div);
8}
9
10// Version 6.0 and after
11Annotation.SignatureWidgetAnnotation.prototype.createInnerElement = function() {
12 const div = document.createElement('div');
13
14 ...
15
16 return div;
17}
It takes a canvas element instead of a jQuery wrapped canvas element.
JavaScript
1// Version 5.x and older
2const signatureTool = docViewer.getTool('AnnotationCreateSignature');
3const canvas = document.createElement('canvas');
4
5signatureTool.setSignatureCanvas($(canvas));
6
7
8// Version 6.0 and after
9const signatureTool = docViewer.getTool('AnnotationCreateSignature');
10const canvas = document.createElement('canvas');
11
12signatureTool.setSignatureCanvas(canvas);
jQuery is no longer accessible inside a config file. The viewerLoaded and documentLoaded events are triggered on the window instead of the wrapped document object now.
JavaScript
1// Version 5.x and older
2$(document).on('viewerLoaded', () => {
3 ...
4});
5$(document).on('documentLoaded', () => {
6 ...
7});
8
9// Version 6.0 and after
10window.addEventListener('viewerLoaded', () => {
11 ...
12});
13window.addEventListener('documentLoaded', () => {
14 ...
15});
Previously this API didn't wait for the resources to be loaded for annotations before exporting them, which may result in an empty ImageData property for stamp annotations. Now this API waits for it internally. This API is deprecated in favor of exportAnnotCommand.
JavaScript
1// Version 5.x and older
2const annots = instance.annotManager.getAnnotationsList();
3Promise
4 .all(annots.map(annot => annot.resourcesLoaded()))
5 .then(() => {
6 const xfdfString = annotManager.getAnnotCommand();
7 });
8
9// Version 6.0 and after
10annotManager.getAnnotCommand().then(xfdfString => {
11 ...
12});
Previously this API didn't wait for the freehand tool to finish drawing before exporting the XFDF, which may result in missing freehand annotations data. It didn't wait for the resources to be loaded as described above. Now the API waits for it internally.
JavaScript
1// Version 5.x and older
2const freehandTool = docViewer.getTool('AnnotationCreateFreeHand');
3const annots = instance.annotManager.getAnnotationsList();
4Promise.all([
5 ...annots.map(annot => annot.resourcesLoaded()),
6 freeHandTool.complete()
7]).then(() => {
8 // to make sure that freehand annotations will be in the output XFDF.
9 const xfdfString = annotManager.exportAnnotations();
10});
11
12// Version 6.0 and after
13annotManager.exportAnnotations().then(xfdfString => {
14 ...
15});
JavaScript
1// Version 5.x and older
2const xfdfString = '...';
3const importedAnnotations = annotManager.importAnnotCommand(xfdfString);
4
5// Version 6.0 and after
6const xfdfString = '...';
7annotManager
8 .importAnnotCommand(xfdfString)
9 .then(importedAnnotations => {
10 ...
11 });
JavaScript
1// Version 5.x and older
2const xfdfString = '...';
3const importedAnnotations = annotManager.importAnnotations(xfdfString);
4
5// Version 6.0 and after
6const xfdfString = '...';
7annotManager
8 .importAnnotations(xfdfString)
9 .then(importedAnnotations => {
10 ...
11 });
JavaScript
1// Version 5.x and older
2const xfdfString = '...';
3const options = {...};
4
5annotManager.importAnnotationsAsync(
6 xfdfString,
7 importedAnnotations => {
8 ...
9 },
10 options,
11);
12
13// Version 6.0 and after
14annotManager
15 .importAnnotations(xfdfString, options)
16 .then(importedAnnotations => {
17 ...
18 });
The Custom property is mainly used to store a custom property to an annotation. Prior to 6.0 you need to extend Annotations.Annotation's serialize and deserialize methods to make sure that this property shows in the exported XFDF. In 6.0 we replace this property with CustomData. The value of it will be serialized to the output XFDF, and even better, be preserved in the downloaded document.
JavaScript
1// Version 5.x and older
2const serialize = Annotations.Annotation.prototype.serialize;
3
4Annotations.Annotation.prototype.serialize = function() {
5 const el = serialize.apply(this, arguments);
6
7 if (this.Custom) {
8 el.setAttribute('custom', this.Custom);
9 }
10
11 return el;
12};
13
14const deserialize = Annotations.Annotation.prototype.deserialize;
15
16Annotations.Annotation.prototype.deserialize = function(el) {
17 deserialize.apply(this, arguments);
18
19 this.Custom = el.getAttribute('custom');
20};
21
22annot.Custom = {
23 isChecked: false,
24};
25
26// Version 6.0 and after
27annot.CustomData = {
28 isChecked: false,
29};
Inside a config file, this function is moved to the readerControl object.
JavaScript
1// Inside a config file
2
3// Version 5.x and older
4const customData = window.ControlUtils.getCustomData();
5
6// Version 6.0 and after
7const customData = window.readerControl.getCustomData();
docViewer.getCompleteRotation now requires a page number as the first parameter.