Annotations and unread counts

Information about a document's annotations can be retrieved with the following APIs.

Getting a document's annotations#

Annotations for a document can be retrieved with the Document.getAnnotations API. For information on getting a user's documents, see the getting user documents guide.

Get unread annotation count#

You can get the total number of unread messages with the Document.unreadCount property. This is useful for display an unread message icon in your UI.

import { CollabClient } from '@pdftron/collab-client'

const client = new CollabClient({...options})
const user = await client.loginAnonymously('Joe');
const document = await user.getDocument('abc');

console.log(document.unreadCount)

Events are triggered whenever this value is changed, so you can keep your UI up to date in real time. See this guide for more information.

Check if annotation is unread#

To check if a singular annotation is unread, use the Annotation.isRead property.

import { CollabClient } from '@pdftron/collab-client'

const client = new CollabClient({...options})
const user = await client.loginAnonymously('Joe');
const document = await user.getDocument('abc');

const annotations = await document.getAnnotations();

for(const annotation of annotations) {
  console.log(`Annotation ${annotation.id} is read: ${annotation.isRead}`);
}

Mark all annotations as read#

You can use the Document.markAllAnnotationsAsRead API to set all annotations in the document to read.

import { CollabClient } from '@pdftron/collab-client'

const client = new CollabClient({...options})
const user = await client.loginAnonymously('Joe');
const document = await user.getDocument('abc');

await document.markAllAnnotationsAsRead();

This will update the unread annotation count of the document.

Maximum Annotation size#

You can use the maxAnnotationSize constructor option to set the maximum annotation size that is allowed to create in bytes.

 const collabClient = new CollabClient({
   ...options,
   maxAnnotationSize: 10000 // in bytes
  })

If an annotation is created above this size, it will be rejected and an annotationSizeError event will be triggered. See this guide for more info.

Prevent annotations from saving in database#

In certain scenarios, you may want to allow the user to create annotations without having them sync to the database and other users.

You can prevent annotations from being synced by using the annotationFilter option.

This function accepts an action (either "add", "modify" or "delete") and the WebViewer Annotation. Return true from this function if you want the annotation to be synced to the database as normal, or return false if the annotation should only be kept locally and not stored in the database.

note

When returning false from this function, the annotation will still be drawn locally for the current user.

This function can be asynchronous.

Example

Prevent new highlight annotations from being synced to the database:

import WebViewer from '@pdftron/webviewer'
import { CollabClient } from '@pdftron/collab-client'

WebViewer({ ...options }).then((instance) => {

  const client = new CollabClient({
    instance,
    annotationFilter: (action, annotation) => {
      if(action === 'add' && annotation instanceof instance.Core.Annotations.TextHighlightAnnotation) {
        // Prevent highlight annotations from being synced
        return false;
      }

      // All other annotations can be synced
      return true;
    }
  })

})

Copying annotations to another document#

Annotations can be copied from one document to another by using the Document.copyAnnotationsToDocument API.

This API will copy any annotations to the new document that don't already exist.

import { CollabClient } from '@pdftron/collab-client'

const client = new CollabClient({...options})
const user = await client.loginAnonymously('Joe');
const document = await user.getDocument('abc');

await document.copyAnnotationsToDocument('other-document-id-here');

Only copy certain annotations#

You may only want to copy certain annotations to another document. To accomplish this, pass a second annotationFilter parameter to copyAnnotationsToDocument. This function is used to filter the annotations that are copied over. The function accepts a WebViewer Annotation and must return a boolean representing if that annotation should be copied over or not.

Only copy rectangle annotations

await document.copyAnnotationsToDocument('other-document-id-here', (annot) => {
  return annot instanceof instance.Core.Annotations.RectangleAnnotation;
});

Only copy annotations with "approved" status

await document.copyAnnotationsToDocument('other-document-id-here', (annot) => {
  return annot.getStatus() === 'Accepted';
});

Copy all children#

The above code will only copy the annotations you return "true" to, but it will not include that annotations children by default. To include an annotations children, pass the "includeChildren" flag as a third parameter.

The code below will copy any annotation with an "Accepted" status, along with all its children.

await document.copyAnnotationsToDocument('other-document-id-here', 
  (annot) => {
    return annot.getStatus() === 'Accepted';
  },
  { includeChildren: true }
);