File Attachment Annotations

File attachment annotations are annotations that represent an attached file in the document. Users can annotate their documents with files that can also be downloaded.

File attachment are created with NoZoom and NoRotate set to true by default. This means they will remain the same size at all zoom levels and will not rotate with the view/page. Stroke color is also used as the primary color of the icons as opposed to fill color.

In the PDF specification, there are no specifications for file restrictions or attachment size limits. WebViewer has provided options to tweaks these from the tool that creates file attachment annotations.

Instantiation

JavaScript (SDK v8.0+)

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager, Annotations } = instance.Core;
    documentViewer.addEventListener('annotationsLoaded', async () => {
      const annot = new Annotations.FileAttachmentAnnotation({
        PageNumber: 1,
        X: 100,
        Y: 50,
        Icon: 'Paperclip',
        StrokeColor: new Annotations.Color(0, 255, 0, 1),
      });
      
      const res = await fetch('https://myserver.com/files/test.pdf');
      const buffer = await res.arrayBuffer();
      await annot.setFileData(buffer, 'application/pdf', 'test.pdf');
      annotationManager.addAnnotation(annot);
      annotationManager.redrawAnnotation(annot);
    });
  });

DocumentViewer#annotationsLoaded FileAttachmentAnnotation Color setFileData AnnotationManager.addAnnotation AnnotationManager.redrawAnnotation

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    const { docViewer, annotManager, Annotations } = instance;
    docViewer.on('annotationsLoaded', () => {
      const annot = new Annotations.FileAttachmentAnnotation();
      annot.PageNumber = 1;
      annot.X = 100;
      annot.Y = 50;
      annot.Icon = 'Paperclip';
      annot.StrokeColor = new Annotations.Color(0, 255, 0, 1);
      
      const res = await fetch('https://myserver.com/files/test.pdf');
      const buffer = await res.arrayBuffer();
      await annot.setFileData(buffer, 'application/pdf', 'test.pdf');
      annotManager.addAnnotation(annot);
      annotManager.redrawAnnotation(annot);
    });
  });

DocumentViewer#annotationsLoaded FileAttachmentAnnotation Color setFileData AnnotationManager.addAnnotation AnnotationManager.redrawAnnotation

XFDF

Element name: fileattachment

JavaScript

<fileattachment page="0" rect="302.410,609.110,316.410,643.110" color="#000000" flags="print,nozoom,norotate" name="c93af20d-a823-b04b-6cae-de26e3202304" title="Guest" subject="File Attachment" date="D:20220721151359-07'00'" creationdate="D:20220721151349-07'00'" icon="Paperclip" mimetype="application/pdf" file="test.pdf">
  <data mode="raw" filter="FlateDecode" encoding="hex" length="4561">...</data>
</fileattachment>

Required properties

PageNumber

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

X

Gets or sets the annotation's x-axis position.

Y

Gets or sets the annotation's y-axis position.

Notable properties

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

Icon

The name of the icon to use for this file attachment annotation. Possible default icon types:

• Graph
• PushPin
• Paperclip
• Tag

Author

The author of the annotation.

Color

Gets or sets the annotation's stroke color.

Hidden

Gets or sets whether the annotation is hidden.

Invisible

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

IsClickableOutsideRect

Gets or sets whether any parts of the annotation drawn outside of the rect are clickable.

Listable

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

Locked

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.

LockedContents

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.

NoDelete

Gets or sets if this annotation can be deleted.

NoMove

Gets or sets whether or not the annotation can be moved.

NoResize

Gets or sets if this annotation can be resized by the user.

NoRotate

Gets or sets if this annotation can be rotated.

NoView

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.

NoZoom

Gets or sets if this annotation scales with the page.

Opacity

Gets or sets the opacity of the annotation.

Printable

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

ReadOnly

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.

StrokeColor

Gets or sets the color of the annotation's stroke.

ToggleNoView

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

Useful methods

getFileData

To get the file data from an attachment annotation, you can use getFileData which will asynchronously return the data as a blob. This can be used to trigger an automatic download of an attachment.

JavaScript (SDK v8.0+)

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager, Annotations } = instance.Core;
    documentViewer.addEventListener('annotationsLoaded', () => {
      const annotList = annotationManager.getAnnotationsList();
      annotList.forEach(async annot => {
        if (annot instanceof Annotations.FileAttachmentAnnotation) {
          const fileData = await annot.getFileData();
          const url = URL.createObjectURL(fileData);
          window.open(url);
        }
      });
    });
  });

getFileData

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager, Annotations } = instance.Core;
    documentViewer.addEventListener('annotationsLoaded', () => {
      const annotList = annotationManager.getAnnotationsList();
      annotList.forEach(async annot => {
        if (annot instanceof Annotations.FileAttachmentAnnotation) {
          const fileData = await annot.getFileData();
          const url = URL.createObjectURL(fileData);
          window.open(url);
        }
      });
    });
  });

getFileData

setFileData

Setting the file data on a file attachment annotation is recommended after construction using setFileData. This requires slightly more information other than just the file data, as you will need to provide the web mimetype of the attachment and filename. The filename can be different and will be used when downloaded.

getFileMetadata

If you need to understand the type of file that is stored in the attachment, you use getFileMetadata to get the mimetype and name of the file from when it was originally attached.

JavaScript (SDK v8.0+)

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager, Annotations } = instance.Core;
    documentViewer.addEventListener('annotationsLoaded', () => {
      const annotList = annotationManager.getAnnotationsList();
      annotList.forEach(async annot => {
        if (annot instanceof Annotations.FileAttachmentAnnotation) {
          const metadata = annot.getFileMetadata();
          console.log(metadata.filename, metadata.mimeType);
        }
      });
    });
  });

getFileData

JavaScript (SDK v6.0+)

WebViewer(...)
  .then(instance => {
    const { documentViewer, annotationManager, Annotations } = instance.Core;
    documentViewer.addEventListener('annotationsLoaded', () => {
      const annotList = annotationManager.getAnnotationsList();
      annotList.forEach(async annot => {
        if (annot instanceof Annotations.FileAttachmentAnnotation) {
          const metadata = annot.getFileMetadata();
          console.log(metadata.filename, metadata.mimeType);
        }
      });
    });
  });

getFileData