Some test text!
Jun 29 2022
by Heather Dinsdale
This guide discusses PDF annotations with JavaScript, and how to add them to your project.
And since PDFTron has much expertise in this field, we’ll also touch on the annotation capabilities in the PDFTron and WebViewer SDK.
Let’s start at the beginning – what is a PDF annotation? It is an object such as text, graphics, highlights, text boxes, or redaction marks that users add to a document. You can incorporate an SDK or library into your solution, which allows users to add annotations to documents.
Annotations are added to an existing document, without changing the underlying PDF content. You can add comments or drawings to the PDF for review and collaboration, or even
Additionally, PDF JavaScript annotations support interactive objects, such as forms and e-signatures. You can embed rich media annotations, including audio, video, even
A popular way to annotate documents is using a web app. You can annotate PDF documents in your project using JavaScript, in addition to annotations via native languages using the PDFTron SDK.
So why embed PDF annotation features into your solution? The answer is easy: because PDF annotations are versatile. (PDFTron supports 35+ types.) The PDF format has annotation types to support many use cases and workflows.
And, as a developer, you can customize documents with annotations programmatically – placing watermarks, hyperlinks, images and other annotations via code.
Annotating Images or Office Files
This article focuses on PDFs, but annotations aren’t limited to just PDFs. You can also add notations or discussion threads to Word documents, contracts or reports, or complex designs and construction drawings.
With the right toolkit, annotations are virtually file-format agnostic. Add them to images, Office files, even videos. For example, dynamic client-side
Your toolkit may also support
Check out our "How to annotate web pages using JavaScript"
Client-Side JS Conversion and Annotation
There are numerous reasons for adding JavaScript annotations in a client-side app.
There are two different ways to use an annotation in a PDF.
The PDF specification supports
Let’s look at some of the different PDF annotation types, and where they fit into applications.
1. Drawing and Shape
Add these annotation types to quickly draw attention to suggestions or edits, over images or blocks of text, or to highlight information in the document. The shapes and drawings provide a very visible way to see reviewers' suggestions.
PDF with a cloud polygon annotation
2. Interactive Form and Signature Widgets
The form fields are a collection of interactive elements. These include text boxes, checkboxes, radio buttons, drop-down lists, or push buttons, which gather user information interactively.
Form fields exist as widget annotations and display independently of the field itself. For example, on a loan document, you can add a signature widget that appears on every page for the primary applicant’s signature. Other pages may require multiple signatures for both the applicant and any co-signers.
Check out our online form builder
An electronic signature annotation added to a PDF
3. Redaction
Use
There are two stages of a redaction annotation:
Use redaction annotation on photos and fields, and add text labels
4. Text
Text annotations add text comments, but text markup annotates the actual text instead,. This is done by highlighting and underlining the text, or adding squiggly lines or text strikeouts to note text to remove or change.
PDF using text annotations like highlighting, underlining, and text comment
5. Rubber Stamp
Use these annotations to add a stamp to your PDF the same as you might stamp a hardcopy document. This conveys a message quickly to the reader, that maybe the PDF is private, confidential, copyrighted, or a draft version. It can also convey the document status during a review, if it’s stamped as Approved, Rejected, etc.
PDF with Approved rubber stamp annotation
6. Rich Media/Multimedia
7. Hyperlink
Adds a
8. Images and File Attachments
Adds images or file attachment annotations to your PDF.
9. Custom annotations
Depending on your toolkit, you can create your own annotations and
For example, change the appearance or behavior of annotations, selection boxes, and control handles. You can also build customized annotations to appear in other PDF viewers.
Check out our custom annotations
A custom triangle shape tool created with WebViewer's custom annotations
10. Measurement
Measurement annotations are common in the construction industry, where they are used to dimension rooms or spaces in drawings, and estimate the necessary materials and labor. Check out our measurement tool
Measure a room's diameter with the measurement tool annotation
So now you know what annotations are, how do you implement them? There are various methods, but only some offer all 26 standard types. The PDFTron SDK supports all standard annotations, plus nine additional types, and custom annotations.
With WebViewer, your users can add annotations directly in the UI, using the annotations toolbar. You can also add annotations to PDFs programmatically, using code to add watermarks directly in the client application.
There are other use cases as well, such as:
Threaded conversations
Annotations can provide
Many PDF viewers add single notes or comments, which is a messy format for reviews and conversations. For example, if a copy editor leaves a comment on a particular paragraph, there’s no easy way for the author to quickly see or respond to it in place. With multiple comments scattered across the page, it becomes nearly impossible to piece together the conversation flow—which is not conducive to discussion or quality output.
Instead, with threaded conversations, the editor can add a comment, and other people can reply directly to it, creating a chain discussion. It keeps the comments and replies tidy, visible, and easy to find and respond to.
For more information about document reviews and sample code:
Measurement
Measurements are commonly used in construction and engineering workflows on PDF drawings exported from CAD and BIM programs. Use annotations with measurement tools to calculate area dimensions, measure between lines, or trace perimeters in engineering drawings in a browser or app with JavaScript. You can also add measurement tools to your application and measure the area, distance, or perimeter for construction plans.
For more information and sample code:
Adding stamps
Much like rubber stamping a real-world document, PDF
Electronic signatures
You can also approve documents you’ve reviewed using an electronic signature annotation. This adds a simple visual signature to your document. It is a visually identifiable autograph, and can be
For more information about e-signatures:
Note: Electronic signatures are created as images, hand drawn, photographs, or typed text. They are not digital signatures, which are more complex, and require a digital ID or certificate from a certification authority (self-signed or a third party).
For more information about digital signatures:
After implementing them, you can add PDF JavaScript annotations in two ways: from the UI, or programmatically.
1. UI-based: For this approach, users access annotations with tools in the viewer interface.
PDFTron adds all annotations, including redactions and watermarks, in the browser client, so no data is sent out to third-party servers, and the information never leaves the browser environment. Since you're relying less on server and network resources, the solution is more reliable and scalable for your users.
2. Programmatically: You can also apply annotations automatically, via code. This includes adding watermarks to sensitive documents.
PDFTron’s WebViewer provides many APIs to interact with and customize annotations programmatically. For more information, see
There are two ways to incorporate PDF annotations with JavaScript – build your own solution, or use an existing library.
1. Create a JavaScript Solution
Creating your own solution gives you more control. However, it requires much work, and understanding minute details. You must carefully conform to the PDF specification, handle edge cases, ensure your annotations work with other widely-used PDF readers, and interoperate with the PDF specification standard XFDF format to store annotations.
2. Use an Existing Solution
Building support for custom annotations, form filling, or signature features requires understanding the entire process -- which is handled automatically within a commercial SDK UI.
For example, the PDFTron SDK supports annotations, even in its trial version, so users can process annotations directly in WebViewer.
WebViewer exposes several APIs to easily add annotations with a professional PDF and Office viewer component. You can then
WebViewer also adds support beyond what’s provided in the PDF specification, including support for custom annotation types.
There are different ways to install WebViewer, but we’ll use NPM for this example.
To use WebViewer for annotations, download and install versions 8.0+ via
Since WebViewer requires static resources to be served (which cannot be bundled), an extra step involves manually copying static files into your dist directory.
WebViewer does not require Node, NPM, or node_modules. It is only recommended to run the samples.
1. Install via NPM
Run the following command in your project:
npm i @pdftron/webviewer
This installs the main JS entrypoint, and downloads static assets required for WebViewer to run.
2. Copy static assets
Next, copy the static assets required for WebViewer to run into a public location that is served via HTTP/HTTPS (usually a dist or build folder). The static files are located in
node_modules/@pdftron/webviewer/public
You can add a script to your package.json that moves the static files for you after your build completes.
This copies all required files into the dist/public folder after your build is complete.
{
"scripts": {
"move-static": "cp -a ./node_modules/@pdftron/webviewer/public/. ./dist/public/webviewer",
"build": "mybuildscript && npm run move-static"
}
}
3. Usage
When using WebViewer in your code, you must tell it where you copied these static files using the path parameter.
For example, if you copied the static files into dist/public/webviewer, your code would look something like this:
import WebViewer from '@pdftron/webviewer'
WebViewer({
path: '/public/webviewer',
}, document.getElementById('viewer'))
.then(instance => {
const { UI, Core } = instance;
const { documentViewer, annotationManager, Tools, Annotations } = Core;
// call methods from UI, Core, documentViewer and annotationManager as needed
documentViewer.addEventListener('documentLoaded', () => {
// call methods relating to the loaded document
});
instance.UI.loadDocument('http://fileserver/documents/test.pdf');
})
For information on the next steps, visit
The PDFTron SDK provides annotations right out of the box, using a toolbar in the UI or programmatically by writing code for the annotation types.
When writing code, add the annotation after the document loads. For example, to add it immediately after the document loads, use the
WebViewer(...)
.then(instance => {
const { documentViewer, annotationManager, Annotations } = instance.Core;
documentViewer.addEventListener('documentLoaded', () => {
// create annotation here
});
});
Annotation type properties and functions are available in the annotation API
For more information and links to samples, visit the
Use the following examples to set annotation permissions, add or edit annotations, or create a drawing annotation. For more information, visit annotation
Annotation
Define your own logic by using the
This function takes a callback function you defined and returns it true if you give the current user permission to modify the annotation, or returns false otherwise.
WebViewer(...)
.then(instance => {
const { annotationManager } = instance.Core;
annotationManager.setPermissionCheckCallback((author, annotation) => {
// the default permission check that is used
// you can combine this with your own custom checks
const defaultPermission = annotation.Author === annotationManager.getCurrentUser();
// any annotation with 50% opacity will also be editable regardless of the author
const customPermission = annotation.Opacity === 0.5;
return defaultPermission || customPermission;
});
});
The following sample code adds or edits annotations using the PDFTron SDK JavaScript PDF annotation library. The sample annotation types include: hyperlink, intra-document link, stamp, rubber stamp, file attachment, sound, text, free-text, line, circle, square, polygon, polyline, highlight, squiggly, caret, and ink.
Learn more about our
Use this example to create a rectangle JavaScript PDF annotation. Creating other types of annotations is similar.
WebViewer(...)
.then(instance => {
const { Annotations, annotationManager, documentViewer } = instance.Core;
documentViewer.addEventListener('documentLoaded', () => {
const rectangleAnnot = new Annotations.RectangleAnnotation();
rectangleAnnot.PageNumber = 1;
// values are in page coordinates with (0, 0) in the top left
rectangleAnnot.X = 100;
rectangleAnnot.Y = 150;
rectangleAnnot.Width = 200;
rectangleAnnot.Height = 50;
rectangleAnnot.Author = annotationManager.getCurrentUser();
annotationManager.addAnnotation(rectangleAnnot);
// need to draw the annotation otherwise it won't show up until the page is refreshed
annotationManager.redrawAnnotation(rectangleAnnot);
})
})
One option is to use XFDF files to save and load annotations. You can use AJAX requests to save and load the XFDF string from the server, and set up the server to write and read XFDF files.
WebViewer(...)
.then(instance => {
const { documentViewer, annotationManager } = instance.Core;
documentViewer.setDocumentXFDFRetriever(async () => {
// load the annotation data
const response = await fetch('path/to/annotation/server');
const xfdfString = await response.text();
// <xfdf>
// <annots>
// <text subject="Comment" page="0" color="#FFE6A2" ... />
// </annots>
// </xfdf>
return xfdfString;
});
// later save the annotation data
// widgets and links will remain in the document without changing so it isn't necessary to export them
annotationManager.exportAnnotations({ links: false, widgets: false }).then(xfdfString => {
fetch('path/to/annotation/server', {
method: 'POST',
body: xfdfString // written into an XFDF file in server
});
// Full samples are available at the end of this section.
})
})
For more information, see
Learn more about PDF annotations from the following resources:
In this article, we described what PDF annotations are and the rich functionality they bring to projects with the right annotation library. We also covered:
To learn more about PDFTron's customizable annotations, visit our
We explain how to open DOCX in an Angular viewer and so much more with PDFTron WebViewer.
Open DOCX files in a Vue web app and more with PDFTron WebViewer.
This article discusses what PDF annotations with JavaScript are, and how to add them to your solution.
PDFTron SDK
COMPANY