Grouping annotations through the AnnotationManager

Grouping annotations can be done in WebViewer both in the UI and programmatically. This can be useful for keeping annotations together and forming more meaningful commentary on your documents. Grouped annotations associate themselves to one primary annotation. Only the comment of the primary annotation will appear in the notes panel.

This is what grouped annotations look like represented in XFDF:

<square page="0" rect="92.533,616.387,228.861,717.911" color="#E44234" flags="print" name="f1b0896d-b173-c01e-27bf-eee16f33ae23" title="Guest" subject="Rectangle" rotation="345.166" date="D:20220411125212-07'00'" creationdate="D:20220411125149-07'00'" />
<circle page="0" rect="141.590,547.820,264.010,660.970" color="#E44234" flags="print" inreplyto="f1b0896d-b173-c01e-27bf-eee16f33ae23" replyType="group" name="c245310b-3704-41ea-46ca-756bd66217ae" title="Guest" subject="Ellipse" date="D:20220411125212-07'00'" creationdate="D:20220411125152-07'00'"/>

Notice the replyType and inreplyto attributes of the circle annotation which refer to the square annotation as the primary.

Grouping annotations through the UI is straightforward. Simply selection the annotations you want to group and press the group button.

Likewise, ungrouping annotations will require first selecting the group and pressing the ungroup button.

Grouping annotations is done through the AnnotationManager. The API is called groupAnnotations and it takes a primary annotation along with an array of annotations that will be grouped with it.

const { annotationManager } = instance.Core;

const annotList = annotationManager.getAnnotationsList();
const primaryAnnot = annotList[0];
const primaryColor = primary.FillColor.toHexString();
// Group annotations of the same color
const secondaryAnnots = annotList.filter(annot => annot.FillColor.toHexString() === primaryColor);

annotationManager.groupAnnotations(primary, secondary);

Grouping an annotation to a group will create another group instead of adding to it, so you must always group to the primary annotation to add a new annotation to the group.

Simlar to grouping annotations, the AnnotationManager also provides the ungroupAnnotations function. This function takes an array of annotations to be ungrouped (regardless of which group they belong in) and it will ungroup them without ungrouping other annotations of their respective groups.

const { annotationManager } = instance.Core;

const annotList = annotationManager.getAnnotationsList();
const groupedAnnots = annotList.filter(annot => annot.isGrouped() && annot.PageNumber === 1);
annotationManager.ungroupAnnotations(groupedAnnots);

A helpful API that will get you all the grouped annotations (both the primary and children) is the getGroupAnnotations API. By passing in any of the annotations that are part of the group, it will provide all the annotations in the group including that one that was passed in.

const { annotationManager } = instance.Core;

const annotList = annotationManager.getAnnotationsList();
annotList.forEach(annot => {
  const group = annotationManager.getGroupAnnotations(annot);
  console.log(group);
});

Although this will return both the primary and the children annotations, it may be helpful to be able to make a distinction between them. The next sections will cover this.

The isGrouped API on annotations will tell you whether the annotation is grouped with another. This will only get you secondary annotations that are grouped to a primary annotation. You can leverage this to determine both the parent and children.

const { annotationManager } = instance.Core;

const annotList = annotationManager.getAnnotationsList();
annotList.forEach(annot => {
  const group = annotationManager.getGroupAnnotations(annot);
  const parent = group.find(annot => !annot.isGrouped());
  const children = group.filter(annot => annot.isGrouped());

  // Use annotations
});

Alternatively, you can make use of the InReplyTo property of a grouped secondary annotation along with getAnnotationById on the AnnotationManager to get the primary annotation.

const primaryAnnotsMap = {};
groupedAnnots.forEach(annot => {
  const primary = annotationManager.getAnnotationById(annot.InReplyTo);
  if (primaryAnnotsMap[primary.Id]) {
    return;
  }
  primaryAnnotsMap[primary.Id] = primary;
});
const primaryAnnots = Object.values(primaryAnnotsMap);

If you have the primary annotation of a group, you can use getGroupedChildren to get all the child annotations that are grouped with it. You could also use this to check for a primary annotation.

const annotList = annotationManager.getAnnotationsList();
annotList.forEach(primary => {
  const children = primary.getGroupedChildren();
  if (children.length > 0) {
    // This is a primary annotation
  }
});

Look into how you can create your own annotations!