Foxit PDF SDK for Web: Annotations

In Foxit PDF SDK for Web, annotations include not only regular PDF annotations but also text markup (think text highlighting, underlining, strikeout, squiggly, etc.), drawing annotations (think shapes like circle, rectangle, arrow), and other annotations, such as notes, free text, as well as standard and dynamic PDF stamping.

Annotation

The annotation supports three types of files to import/export data: XFDF, FDF and JSON. The following table lists what annotations currently support or not supported to import/export.

File Type	If all annots support	What not support
XFDF/FDF	Mostly	Link
JSON	Mostly	Screen Image, Link, Sound

API

The following table lists methods that can be used to import/export from/to data file.

Method	XFDF/FDF	JSON	JSON
Import	PDFDoc.importAnnotsFromFDF()	PDFDoc.importAnnotsFromJSON(annotsJson)	PDFPage.addAnnot(annotJson)
Export	PDFDoc.exportAnnotsToFDF()	PDFDoc.exportAnnotsToJSON()	Annot.exportToJson()

We recommend to use a corresponding method to import and export data. For example, if PDFDoc.exportAnnotsToJSON() is called to export data, then it would better if the PDFDoc.importAnnotsFromJSON(annotsJson) method is used to import.

Note: Adding exported JSON data to the document via the PDFPage.addAnnot method can lead to loss of binary data streams for some annotations, such as Stamp and fileAttachment. This is because the PDFPage.addAnnot method does not support JSON data that contains binary streams. Therefore, if the data exported by PDFDoc.exportAnnotsToJSON contains binary streams, then it cannot be passed to the PDFPage.addAnnot method.

var pdfViewer = await pdfui.getPDFViewer(); 
var test = {ExportDataFile:'http://pathToSourceFile.pdf',ImportDatafile:'http://pathToTargetFile.pdf'}; 
var resp = await fetch(test.ExportDataFile); 
var file = await resp.blob(); 
 
var pdfdoc = await pdfViewer.openPDFByFile(file); 
var annotJson = await pdfdoc.exportAnnotsToJSON(); 
var newResp = await fetch(test.ImportDatafile); 
var newFile = await newResp.blob() 
 
var newPdfdoc = await pdfViewer.openPDFByFile(newFile); 
for(var i=0;i<annotJson.length;i++){ 
var newPage = await newPdfdoc.getPageByIndex(annotJson[i].page); 
var newAnnot = await newPage.addAnnot(annotJson[i]); 
} 

Stamp and customization

Foxit PDF SDK for Web provides a wide range of stamp features that users can implement with APIs and default icons. This section will walk you through how manage stamps and add a stamp into a PDF.

Default stamp list

Foxit PDF SDK for web provides a default stamp list in Viewer as follows:

{ 
"stamp": { 
"Static": { 
"Approved": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Completed": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Confidential": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Draft": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Revised": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Emergency": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Expired": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Final": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Received": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Reviewed": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
} 
}, 
"SignHere": { 
"Accepted": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Initial": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Rejected": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"SignHere": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Witness": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
} 
}, 
"Dynamic": { 
"Approved": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Confidential": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Received": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Reviewed": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
}, 
"Revised": { 
"url": "xxx://url.url", 
"fileType": "pdf" 
} 
} 
} 
} 

Add a stamp onto page in Viewer

The stamp list can be found by dropping down the stamp tool under Comment tab in Viewer. You can click a stamp icon and place it to a desired place on the page.

If you want to create a custom stamp and add it onto page, follow the steps below:

1) In Advanced Web Viewer, drop down the stamp tool under Comment tab，select Custom Stamps.

2) In the pop-up Create Custom Stamp dialog box, click File -> Browse… and choose an image file, or click File -> Enter File URL, input the URL address where the PDF and svg files are stored.

3) Fill in the category, name, width and height, as well as choose a type from drop-down menu to create a stamp. Then, the created stamp will appear in the Stamp list.

4) Click the created stamp icon and place it to a desired place on the page.

Add a custom stamp onto page by API

Before calling the PDFPage.addAnnot to add a custom stamp which doesn’t exist in your stamp list, you should call PDFViewer.addAnnotationIcon() to add it into stamp list. If not doing this, the stamp appearance will display incorrectly on the page.

var icons = { 
annotType: "stamp", 
fileType: "png", 
url: "http://stamp.png", 
// width:80, 
// height:30, 
category: "MyCategory", 
name: "MyStamp" 
}; 
 
var stamp = { 
type:'stamp', 
rect:{left:0,bottom:0,right:200,top:100}, 
icon:'MyStamp', 
iconCategory:'MyCategory' 
}; 
 
var pdfViewer = await pdfui.getPDFViewer(); 
var pdfDoc = await pdfViewer.getCurrentPDFDoc(); 
var page = await pdfDoc.getPageByIndex(0); 
 
await pdfViewer.addAnnotationIcon(icons); 
await page.addAnnot(stamp) 

If you only want to add a new stamp onto the page without adding the stamp icon in your stamp list of your viewer, you can run the following code:

pdfpage.addAnnot({ 
type: PDFViewCtrl.PDF.annots.constant.Annot_Type.stamp, 
rect: { left: 0, right: 300, top: 450, bottom: 0 }, 
iconInfo: { 
annotType: PDFViewCtrl.PDF.annots.constant.Annot_Type.stamp, 
category: "category", 
name: "name", 
fileType: "pdf", 
url: "http://path/file.pdf" 
} 
}); 
 

Manage Stamp list

The default stamp list doesn’t allow changes. However, you can create your own stamps to replace the default ones, and then edit them. The first step is to make a PDF and corresponding svg file. You can refer to the examples in lib\stamps\en-US\DynamicStamps folder.

Create a custom stamp list

A custom stamp list can be predefined by calling the API pdfViewer.initAnnotationIcons() and loaded into the viewer. Once the following code runs, the default stamp list will be overwritten.

var initIcons = { 
MyCategory1: { 
StampName1: { 
fileType: "jpg", 
url: "http://stamp.jpg" 
} 
}, 
MyCategory2: { 
StampName2: { 
fileType: "png", 
url: "stamp.png" 
} 
}, 
... 
}; 
var pdfViewer = await pdfui.getPDFViewer(); 
await pdfViewer.initAnnotationIcons({ stamp: initIcons }); 

Remove custom stamps

//remove a stamp with the category and name as 'MyCategory1' and 'StampName1' from you stamp list 
var pdfViewer = await pdfui.getPDFViewer(); 
await pdfViewer.removeAnnotationIcon('stamp','MyCategory1','StampName1') 
//clear the whole stamp list 
var pdfViewer = await pdfui.getPDFViewer(); 
await pdfViewer.removeAnnotationIcon('stamp','','StampName1') 
//clear all stampes under 'MyCategory1'  
var pdfViewer = await pdfui.getPDFViewer(); 
await pdfViewer.removeAnnotationIcon('stamp','MyCategory1','') 

Add a new custom stamp

var icons = { 
annotType: "stamp", 
fileType: "png", 
url: "http://stamp.png", 
// width:80, 
// height:30, 
category: "MyCategory", 
name: "MyStamp" 
}; 
var pdfViewer = await pdfui.getPDFViewer(); 
await pdfViewer.addAnnotationIcon(icons); 

About the stamp category and name

Stamps are organized by category and name. To find out what stamps already exist in your list, the easy way is to check the category and name information by calling pdfui.getAnnotationIcons(). Here are code samples.

Get the stamp category and name

//list all available stamps 
await pdfui.getAnnotationIcons("stamp", false); 
//list only custom stamps 
await pdfui.getAnnotationIcons("stamp", true); 

You also execute the following code to output the existing stamps.

var allIcons = pdfui.getAnnotationIcons("stamp", false); 
var iconNames = []; 
for (var categoryKey in allIcons) { 
var category = allIcons[categoryKey]; 
for (var name in category) { 
iconNames.push({ 
category: categoryKey, 
name 
}); 
} 
} 
console.log(iconNames); 

Set the default tool to a particular stamp in Viewer

Use the PDFUI constructor option to define a stamp as the default tool handler:

pdfui = new UIExtension.PDFUI({ 
customs: { 
defaultStateHandler: PDFViewCtrl.STATE_HANDLER_NAMESSTATE_HANDLER_CREATE_STAMP 
handlerParams: { 
category: 'SignHere', 
name: 'SignHere' 
} 
}; 
}) 

Use the API StateHandlerManager.switchTo() to set default tool:

pdfui.getStateHandlerManager().then(handlerManager => 
handlerManager.switchTo( 
PDFViewCtrl.STATE_HANDLER_NAMES.STATE_HANDLER_CREATE_STAMP, 
{ 
category: "SignHere", 
name: "SignHere", 
url: "http://xxx/xx.png",// or "blob:http://xxxxx" 
showUrl: "http://xxx/xx.png",// or "blob:http://xxxxx" 
fileType:'png', 
width:80, 
height:30, 
} 
) 
); 

Add stamp to a cropped page

var pdfviewer = await pdfui.getPDFViewer(); 
var pdfdoc = await pdfviewer.getCurrentPDFDoc(); 
var page = await pdfdoc.getPageByIndex(0); 
var rect = await page.getPageBox(PDFViewCtrl.PDF.constant.Box_Type.MediaBox); 
if(page.isCropped()){ 
//The rect transformation between the original page coordinates to visible page coordinates. 
var matrix = await page.getPDFMatrix(); 
matrix.setReverse(matrix); 
var rectArr = matrix.transformRect(rect.left, rect.top, rect.right, rect.bottom); 
rect = {left: rectArr[0], bottom: rectArr[1], right: rectArr[2], top: rectArr[3]}; 
} 
var json = {type:'stamp',rect: 
{left:0,right:400,top:250,bottom:0}, 
iconInfo:{annotType: "stamp",catagory: "catagory",name: "customStampName1", fileType: "jpg", url:'http://10.103.4.217:9898/image/IMG_8567.HEIC.JPG'}} 
await page.addAnnot(json); 

Related APIs

APIs	Description
PDFViewer.initAnnotationIcons(icons)	Initialize the icon of the annotation (after setting, the default icon will not be displayed)
PDFViewer.addAnnotationIcon(icon)	Add a single icon
PDFViewer.removeAnnotationIcon(type,category,name)	Remove a single icon
PDFUI.getAnnotationIcons(annotType,onlyCustomized)	Get custom icon
StateHandlerManager.switchTo(name,params)	Switch to addStampStateHandler
PDFViewer.setFormatOfDynamicStamp(seperator,timeFormat)	Set the format of dynamic information
PDFPage.addAnnot(json)	Add stamp with specifying the existing icon as the style of stamp