Comments and Markup¶

Freehand text comments¶

Users can add freehand text anywhere on a PDF page as follows: select the Add Text tool in the top bar, click on the page to place the cursor and type in your desired text. Click outside the text box to add the annotation. A comment with the same text also appears in the right-hand comments panel. Features include:

• Updating free text annotation: Click on an existing add text annotation to edit the text or change any of the text attributes from the toolbar. You can change attributes such as colour and font size of the free text. Note: The display of the text size is relative to the PDF zoom level. Text can also be edited by clicking on the Edit option in the overflow menu for the associated comment in the comments panel.

• Removing free text annotation

  • Click any existing add text annotation to open the toolbar, and choose Delete.

  • Alternatively, click the overflow menu for the associated comment in the comments panel, and choose Delete.

• Moving or resizing free text annotation: Place the cursor on an existing add text annotation and move the free text to a different location on the same PDF page. You can also drag one of the corner circles of the text box to resize.

Sticky notes¶

Use the sticky note to add a text message and place it anywhere on the PDF. There is no support for resizing. Features include:

• Adding a sticky note

  • Select the sticky note tool in the top bar and click where you want to place the note. This opens a comment box where you can type in some text. Click Post to add the comment.

  • You can also add a sticky note by performing right-click and selecting Add sticky note option from the popover menu.

• Updating sticky note

  • Click on an existing sticky note to open a toolbar to change the colour of the note.

  • Edit the comment by clicking on the Edit option in the overflow menu in the comments panel.

• Removing sticky note

  • Click on an existing sticky note to open the toolbar and click on delete option to remove the note.

  • Alternatively, click on the overflow menu for the comment in the comments panel and click on the Delete option.

• Moving a sticky note: Place the cursor over an existing sticky note and drag to move it to some other location.

Text markup annotations¶

Embed API supports the following highlighting, strikethrough, and underlining. Features include:

• Adding a text markup: There are two ways to add a text markup:

  • Click the highlight tool in the top bar and select some text. The text gets highlighted and a comment box opens up where you can type in some text.

  • Select some text. Select either the highlight, strikethrough or underline options from the context menu. The markup is added and a comment box opens up where you can type in some text.

• Updating a text markup: While moving or resizing text markup is unsupported, you can:

  • Click on an existing text markup to open a toolbar to change the colour.

  • You can edit the comment by clicking on the Edit option in the overflow menu in the comments panel.

• Removing a text markup

  • Click on an existing text markup to open the toolbar, and choose Delete.

  • Click on the overflow menu for the comment in the comments panel, and choose Delete.

Drawing tool¶

Use this tool to create any freehand drawing or shape. Features include:

• Adding a drawing

  • Select the drawing tool in the top bar, click where you want to begin drawing and drag to create a shape. You can release the mouse button, move the pointer to a new location, and continue drawing. The drawing gets added along with a default comment in the comments panel.

  • You can also add a drawing by performing right-click and selecting Use drawing tool option from the popover menu.

• Updating a drawing

  • Click on an existing drawing to display the toolbar. You can change attributes such as colour and stroke width.

  • You can edit the comment by clicking on the Edit option in the overflow menu in the comments panel.

• Removing a drawing

  • Click on an existing drawing to display the toolbar and click on the delete option.

  • Alternatively, click on the overflow menu for the comment in the comments panel and click on the Delete option.

• Moving or resizing a drawing

  • Place the cursor over a drawing and drag to move it to a different location.

  • Place the cursor over a drawing and drag one of the corner circles to resize the annotation.

Eraser tool¶

This tool can be used to erase parts of freehand drawing annotations you added via the drawing tool.

Select the eraser tool in the top bar and drag it across the areas of the drawing annotation that you wish to remove. The updated drawing annotation is saved to the PDF.

• Parts of a single drawing or multiple drawing annotations can be erased at the same time. The corresponding drawing annotations are updated in the PDF.

• If the entire drawing is erased, then that particular drawing annotation gets removed from the PDF.

Annotation data examples¶

You can find addtional samples and examples code in the samples repo.

{
      "@context": [
          "https://www.w3.org/ns/anno.jsonld",
          "https://comments.acrobat.com/ns/anno.jsonld"
      ],
      "type": "Annotation",
      "id": "079d66a4-5ec2-4703-ae9d-30ccbb1aa84c",
      "bodyValue": "I added a note!",
      "motivation": "commenting",
      "target": {
          "source": "77c6fa5d-6d74-4104-8349-657c8411a834",
          "selector": {
              "node": {
                  "index": 1
              },
              "opacity": 0.4,
              "subtype": "note",
              "boundingBox": [
                  69.3311157226562,
                  76.4769897460938,
                  86.9484252929688,
                  94.63037109375
              ],
              "strokeColor": "#ff0808",
              "type": "AdobeAnnoSelector"
          }
      },
      "creator": {
          "type": "Person",
          "name": "John Smith"
      },
      "created": "2018-08-02T14:45:37Z",
      "modified": "2020-01-20T07:54:10Z"
 }

{
   "@context": [
       "https://www.w3.org/ns/anno.jsonld",
       "https://comments.acrobat.com/ns/anno.jsonld"
   ],
   "type": "Annotation",
   "id": "eb46d1a9-e9c3-4e81-a6f4-ce5ba7a905e9",
   "bodyValue": "Reply to this",
   "motivation": "replying",
   "target": {
       "source": "079d66a4-5ec2-4703-ae9d-30ccbb1aa84c"
   },
   "creator": {
       "type": "Person",
       "name": "Samuel Lee"
   },
   "created": "2020-02-02T14:45:37Z",
   "modified": "2020-02-02T07:57:03Z"
}

{
      "@context": [
          "https://www.w3.org/ns/anno.jsonld",
          "https://comments.acrobat.com/ns/anno.jsonld"
      ],
      "type": "Annotation",
      "id": "02dcf931-d1cb-49c1-a8bc-d047892a06bc",
      "bodyValue": "I added a text annotation",
      "motivation": "commenting",
      "stylesheet": {
          "type": "CssStylesheet",
          "value": "body-value-css { font: 13px Helvetica; color: #0000FF; }"
      },
      "target": {
          "source": "77c6fa5d-6d74-4104-8349-657c8411a834",
          "selector": {
              "node": {
                  "index": 1
              },
              "subtype": "freetext",
              "boundingBox": [
                  306.41829735235586,
                  339.01199687491595,
                  475.729044456285,
                  357.0653042030006
              ],
              "styleClass": "body-value-css",
              "type": "AdobeAnnoSelector"
          }
      },
      "creator": {
          "type": "Person",
          "name": "John Smith"
      },
      "created": "2021-01-15T14:45:37Z",
      "modified": "2021-01-15T14:45:37Z"
 }

addAnnotations API¶

This API adds or imports (only) supported annotations. It takes a JSON array as input which contains the annotation data. The annotation data must be in the specified in the Annotation schema. Either a single annotation or multiple annotations can be added.

const list_of_annotations = [Annotation_1, Annotation_2, ...];

previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                        annotationManager.addAnnotations(list_of_annotations)
                                        .then(() => console.log("Success"))
                                        .catch(error => console.log(error));
         });
});

getAnnotations API¶

This API exports and receives PDF annotation data based on the filter provided by the client. The annotations are returned in the form of a JSON array, and the annotation data will be in the format as described in the Annotation schema.

filter = {
        annotationIds:
                [Annotation_ID_1, Annotation_ID_2, ...],
        pageRange:{
                startPage: <Page_Number>,
                endPage: <Page_Number>
        },
}

const filter = {
        // annotationIds: [Annotation_ID_1, Annotation_ID_2, ...];
        // OR,
        // pageRange: {startPage: <Page_Number>, endPage: <Page_Number>};
}


previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                        annotationManager.getAnnotations(filter)
                                        .then (result => console.log(result))
                                        .catch(error => console.log(error));
 });
});

deleteAnnotations API¶

This API deletes PDF annotations based on the filter provided by the client.

const filter = {
        // annotationIds: [Annotation_ID_1, Annotation_ID_2, ...];
        // OR,
        // pageRange: {startPage: <Page_Number>, endPage: <Page_Number>};
}

previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                        annotationManager.deleteAnnotations(filter)
                                        .then (() => console.log("Success"))
                                        .catch(error => console.log(error));
 });
});

updateAnnotation API¶

This API updates a single existing PDF annotation in the PDF, including the parameters bodyValue, font and color under stylesheet as well as other parameters under selector such as, strokeColor, strokeWidth, boundingBox, quadPoints and inkList.

This API takes the annotation data containing the updated parameters, finds the annotation with the ID present in the input data, and applies the update to that annotation. The annotation data must be in the format as described in theAnnotation schema.

const annotation_data = <Annotation_Data>;

previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                        annotationManager.updateAnnotation(annotation_data)
                                        .then (()=> console.log("Success"))
                                        .catch(error => console.log(error));
 });
});

Events callback usage¶

Register the events callback and enable the flag enableAnnotationEvents to receive these events.

For details, see Annotation events

annotationManager interface¶

The annotationManager interface listens for events via the registerEventListener API. To receive specific event types, pass the list of event types in the listenOn parameter. If nothing is passed to listenOn, then all the annotation events return.

Note that the events are generated through this interface only when annotation APIs are enabled.

const eventOptions = {
  // Pass the events to receive.
  // If no event is passed in listenOn, then all the annotation events will be received.
  listenOn: [
      "ANNOTATION_ADDED", "ANNOTATION_CLICKED"
  ]
}

previewFilePromise.then(adobeViewer => {
  adobeViewer.getAnnotationManager().then(annotationManager => {
      annotationManager.registerEventListener(
          function(event) { console.log(event.type, event.data) },
          eventOptions
      );
   });
});

Possible annotations events appear in the following table. The event data contains the data of the annotation in JSON format on which the event gets triggered.

removeAnnotationsFromPDF API¶

This API deletes all annotations and returns both a list of the removed annotations as well as the PDF buffer as output. Note that the API can only remove supported annotations.

previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                        annotationManager.removeAnnotationsFromPDF()
                                        .then(result => console.log(result))
                                        .catch(error => console.log(error));
         });
});

addAnnotationsInPDF API¶

This API takes a list of supported annotations as input and saves those annotations to the PDF buffer. The updated PDF buffer is returned as API output.

const list_of_annotations = [Annotation_1, Annotation_2, ...];

previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                        annotationManager.addAnnotationsInPDF(list_of_annotations)
                                        .then(result => console.log(result))
                                        .catch(error => console.log(error));
         });
});

setConfig API¶

setConfig allows you to set special UI configurations, including hiding the commenting tools from the top bar, hiding the right-hand comments pane, hiding the toolbar on text selection, and enabling the downloaded and printed PDF to contain annotations even when unsaved to the PDF buffer.

The API supports the following flags. You can pass 1-N flags to the API as needed:

• showToolbar: This flag shows or hides the add text, sticky note, highlight, drawing and eraser tools in the top bar. The default value is true, and these annotation tools are visible. Set this flag to false if these tools need to be hidden from the top bar.

• showCommentsPanel: This flag shows or hides the right-hand comments pane. The default value is true, and the comments pane is visible. Set to false to hide the right-hand comments pane.

• showToolsOnTextSelection: This flag shows or hides the toolbar available on text selection. The default value is true, and the toolbar is visible. Set to false to hide the toolbar.

• downloadWithAnnotations: Annotations are not saved to the PDF buffer if annotation APIs are enabled. By default, the downloaded PDF will not contain any annotation. Set to true to download the PDF with all the annotations.

• printWithAnnotations: Annotations will no longer be saved to the PDF buffer if annotations APIs are enabled. By default, the print does not contain any annotation. Set to true to print the PDF with all the annotations.

Method 1: Pass the flags to setConfig

{
       showToolbar: <Boolean, Default=true>,
       showCommentsPanel: <Boolean, Default=true>,
       downloadWithAnnotations: <Boolean, Default=false>,
       showToolsOnTextSelection: <Boolean, default=true>,
       printWithAnnotations: <Boolean, Default=false>
}

       const customFlags = {
               showToolbar: <Boolean, Default=true>,
               showCommentsPanel: <Boolean, Default=true>,
               downloadWithAnnotations: <Boolean, Default=false>,
               showToolsOnTextSelection: <Boolean, default=true>,
               printWithAnnotations: <Boolean, Default=false>,
}

previewFilePromise.then(adobeViewer => {
               adobeViewer.getAnnotationManager().then(annotationManager => {
                               annotationManager.setConfig(customFlags)
                                               .then(() => console.log("Success"))
                                               .catch(error => console.log(error));
               });
});

Method 2: Pass the flags to previewFile

As an alternative to passing to setConfig, add the flags to the annotationUIConfig object that’s passed as a preview configuration to the previewFile API.

annotationUIConfig: {
  showToolbar: <Boolean, default=true>,
  showCommentsPanel: <Boolean, default=true>,
  showToolsOnTextSelection: <Boolean, default=true>,
  downloadWithAnnotations: <Boolean, default=false>,
  printWithAnnotations: <Boolean, default=false>
}

selectAnnotation API¶

This API selects any existing annotation and shifts the focus to the selected annotation. It applies the select operation to the annotation specified by the annotation ID.

const annotation_ID = <Annotation_ID>;

       previewFilePromise.then(adobeViewer => {
               adobeViewer.getAnnotationManager().then(annotationManager => {
                               annotationManager.selectAnnotation(annotation_ID)
                                               .then(() => console.log("Success"))
                                               .catch(error => console.log(error));
        });
       });

unselectAnnotation API¶

This API unselects the last selected annotation.

previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                        annotationManager.unselectAnnotation();
 });
});

startAnnotationMode API¶

This API starts a particular annotation mode so that you can annotations of that type or use the eraser tool. The API takes a single annotation mode as input. The annotation mode can be any one of the supported annotation types in PDF Embed API, and it supports the following optional parameters:

• defaultColor: A hex code specifying the annotation color. This parameter is applicable for all annotation types.

• cursor: A CSS standards-based string value to denote the cursor style on annotation start. This parameter is applicable for all annotation types.

• fontSize: Font size within the range of 6-24px. This parameter is applicable only in case of freehand text annotations.

const mode = "freetext";
const options = {
  defaultColor: "#b80000",
  cursor: "crosshair",
  fontSize: "15px"
};

previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                annotationManager.startAnnotationMode(mode, options)
                        .then(result => console.log(result))
                        .catch(error => console.log(error));
   });
});

endAnnotationMode API¶

This API ends the last started annotation mode.

previewFilePromise.then(adobeViewer => {
        adobeViewer.getAnnotationManager().then(annotationManager => {
                annotationManager.endAnnotationMode();
   });
});