Custom Annotations

Custom annotations in WebViewer allow you to create annotations that will suit your needs and use case. They can have custom rendering and functionality. They can also be preserved in the document to view in other viewers or reloaded in your app without additional conversion. However, they will lose all custom functionality in other viewers since they are custom and only exist in your app.

Check out our custom annotation guide that will guide you through making a custom triangle annotation!

WebViewer(
  // ...
).then(function(instance) {
  const { Annotations } = instance.Core;

  class TriangleAnnotation extends Annotations.CustomAnnotation {
    constructor() {
      super('triangle'); // Provide the custom XFDF element name. You can provide an object initializer as a second parameter.
      this.Subject = 'Triangle';
    }
  }

  // This is necessary to set the elementName before instantiation
  TriangleAnnotation.prototype.elementName = 'triangle';
});

Element name: stamp or varies

<stamp page="0" rect="249.460,610.030,340.110,688.120" color="#000000" flags="print" name="12a17eba-e0a2-0baf-9fe5-5fa1e314e485" title="Guest" subject="Triangle" date="D:20220729130723-07'00'" creationdate="D:20220729130718-07'00'" vertices="294.785,688.12;340.11,610.03;249.46,610.03">
  <trn-custom-data bytes="{"trn-annot-type":"triangle","trn-annot-data":"{}"}"/>
  <imagedata>...</imagedata>
</stamp>

Gets or sets the page number of a document that the annotation appears on.

For the full list of properties, please visit the annotation's API docs.

A constant of custom annotation serialization method types to use with SerializationType. Possible values are:

• STAMP
• CUSTOM

Gets or sets the quality of the annotation when saved as a stamp. The higher the value, the higher the quality and memory usage. The default is 2.

Gets or sets the method this annotation class will be saved with. Possible values can be found on the SerializationTypes constant. The default is STAMP.

Gets or sets the additional padding around the custom annotation stamp appearance.

Gets an object that can be used to store primitive, custom data. Data set on this object will be saved to the annotations custom data automatically which gets preserved in the document. This property cannot be initialized through the initializer.

The author of the annotation.

Gets or sets the annotation's stroke color.

Gets or sets whether the annotation is hidden.

Gets or sets whether the annotation is invisible, only if it is an unknown annotation type. Generally for hiding annotations you should use "Hidden".

Gets or sets whether the annotation should be listed in annotation lists. If set to false, the annotation will also become unselectable.

Gets or sets whether the annotation is locked or not. If it's locked it can't be edited or deleted, but the note can be edited.

Gets or sets whether the annotation contents are locked or not. If the contents are locked then note can't be edited but the annotation can be edited or deleted.

Gets or sets if this annotation can be deleted.

Gets or sets if this annotation can be rotated.

Gets or sets whether the annotation is visible on the screen. Differs from Hidden in that it can still be printed if the print flag is set.

Gets or sets if this annotation scales with the page.

Gets or sets the opacity of the annotation.

Gets or sets whether the annotation should be displayed when printing the page.

Gets or sets whether the annotation is readonly or not. If it's readonly both the annotation itself and its note can't be edited or deleted.

Gets or sets whether the ToggleNoView flag is set on the annotation.

If you need to create a custom annotation class based on an existing annotation class, the createFromClass static, utility function makes it easy. Just provide the new custom element name as well as the base annotation class.

WebViewer(
  // ...
).then(function(instance) {
  const { Annotations, annotationManager } = instance.Core;

  // Create my custom rectangle class based on a rectangle annotation
  const MyRectangle = Annotations.CustomAnnotation.createFromClass('myrect', Annotations.RectangleAnnotation);

  // Register custom annotation class with the annotation manager
  annotationManager.registerAnnotationType('myrect', MyRectangle);

  // Customize drawing
  const origDraw = MyRectangle.prototype.draw;
  MyRectangle.prototype.draw = function(ctx) {
      origDraw.apply(this, arguments);

      ctx.save();
      ctx.fillStyle = '#000000';
      ctx.fillText('My Rect', this.X, this.Y + 12); // This refers to the annotation object.
      ctx.restore();
  }

  documentViewer.addEventListener('annotationsLoaded', () => {
    // Create the annotation
    const annot = new MyRectangle({
        PageNumber: 1,
        X: 50,
        Y: 50,
        Width: 100,
        Height: 25,
    });
    instance.Core.annotationManager.addAnnotation(annot);
    instance.Core.annotationManager.redrawAnnotation(annot);
  });
});

Custom annotations exist outside of the PDF specification. As such, specification compliant viewers will not understand these annotations and ignore them.

WebViewer is a compliant viewer that allows you to support your custom annotations if you wish. WebViewer even allows the annotations to exist in other compliant viewers. This is done by saving it as a stamp, rather than its custom type, which will allow the annotation to appear in other viewers.

When the document is reloaded in WebViewer (where the custom annotation is registered and supported), WebViewer can deserialize the annotation back into its original custom type. This is done through storing the unique element type of the custom annotation in the custom data.

If you would prefer to store the XFDF only, as opposed to a stamp, and would like the custom type to appear in the XFDF, then you can change the static property SerializationType on the custom annotation class to SerializationTypes.CUSTOM.

Custom annotations offer a wide possibility of options to work with. It should come without saying that custom annotations can be drawn in various ways as well and possibly beyond it's own bounds. When this happens, the annotation may be clipped after saving as stamp annotations, as the image cannot exist beyond the rectangular bounds of the stamp.

You can use the OutputImagePadding to pad the annotations of the custom class to ensure the annotation renders in its entirety when saved. However, this adds padding and shrinks the annotation a bit based on the amount of padding added.