# AnnotationAuthorityManager

Before formally introducing how to use the AnnotationAuthorityManager utility class, let's first understand the types of annotation permissions and how to set them.

# Types of Annotation Permissions

There are three types of annotation permissions:

PDF annotation permissions: Restrictions on the operations of annotation within the PDF document itself. You can use the User_Permissions (opens new window) ( for global) or Annot_Flags (opens new window) (for a single annotation) to set it. The settings for PDF annotation permissions will be written into the document, thus changing the document.
View annotation permissions: Restrictions on the operations of annotation from the view layer. The settings for view annotation permissions only affect the application and are not written into the document, so that it will not change the document.
Interactive annotation permissions: The intersection of PDF annotation permissions and view annotation permissions is called interactive annotation permissions. After loading a PDF document, users will have restrictions on their actions towards annotations based on the interactive annotation permissions.

# The method for setting annotation permissions

Foxit PDF SDK for Web provides four ways to set annotation permissions as follows:

Set view annotation permissions through the PDFViewer constructor. For example, [options.customs.getDocPermissions=(doc:PDFDoc)=>-1] (opens new window) and [options.customs.getAnnotPermissions=(annot:Annot)=>Promise.resolve()] (opens new window).
Set view annotation permissions dynamically in real-time using the AnnotationAuthorityManager utility class. See setAnnotPermissionCallback (opens new window).
Set PDF annotation permissions globally through the PDFDoc::setPasswordAndPermission (opens new window) interface.
Set PDF annotation permissions for a single annotation through the Annot:setFlags (opens new window) interface.

# The Usage of AnnotationAuthorityManager

You can update interactive annotation permissions by setting PDF annotation permissions or view annotation permissions. In some scenarios, you may not want to modify the original document and only want to control the user's operation permissions on annotations at the application layer. In this case, you can use the AnnotationAuthorityManager utility class to set the view annotation permissions for annotations in real-time and then update the interactive annotation permissions.

Note: When the application layer updates the interactive annotation permissions, Foxit PDF SDK for Web internally takes the intersection of the view annotation permissions set by the application layer and the PDF annotation permissions to determine the final interactive permissions that users have on annotations.

# Timing for updating interactive annotation permissions

The following example code demonstrates how users can passively or actively update the interactive annotation permissions.

Update the interactive annotation permissions passively

Before opening a document, users can set permissions first using setAnnotPermissionCallback (opens new window), [options.customs.getDocPermissions=(doc:PDFDoc)=>-1] (opens new window), and [options.customs.getAnnotPermissions=(annot:Annot)=>Promise.resolve()] (opens new window). After the document is opened, the SDK will update the interactive annotation permissions automatically, and users do not need to set them again.

Note: Here, "passive update" means that the SDK will automatically update the interactive annotation permissions after the document is opened, without the need for the user to manually call an interface to update them.

    // There are two ways to set the view annotation permissions before the document is opened:

    // The first method is to set the view annotation permissions based on the annotation information when constructing the PDFViewer object
    const pdfui = new PDFUI({
        viewerOptions: {
            customs:{
                // Set the view annotation permissions
                getAnnotPermissions:function(annot){
                    const ANNOTATION_PERMISSION = UIExtension.PDFViewCtrl.constants.ANNOTATION_PERMISSION
                    // Set to have all the view annotation permissions
                    return Promise.resolve([ANNOTATION_PERMISSION.fully]);
                }
            }
        }
    })

    // The second method is to set the view annotation permissions through the AnnotationAuthorityManager manager
    const pdfViewer = await pdfui.getPDFViewer();
    // Get the AnnotationAuthorityManager manager.
    const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
    // Set the view annotation permissions
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // Set to have no operation permissions
        return Promise.resolve([]); 
    })

    // When opening a PDF document, the SDK will read the view annotation permissions that you set, and then update the interactive annotation permissions automatically.
    pdfui.openPDFByHttpRangeRequest('http:xxx');

Update the interactive annotation permissions actively

After the document is opened, users can dynamically set permissions and then actively update interactive annotation permissions using updateAll() (opens new window) or update() (opens new window) method.

    // Open a document
    pdfui.openPDFByHttpRangeRequest('http:xxx');
    
    // Set the view annotation permissions through the AnnotationAuthorityManager manager
    const pdfViewer = await pdfui.getPDFViewer();
    // Get the AnnotationAuthorityManager manager
    const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
    // Set the view annotation permissions 
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // Set to have no operation permissions for all annotations
        return Promise.resolve([]);
    })

    // Need to manually update the interactive permissions of all annotations, otherwise the view annotation permissions you set will not take effect immediately
    await annotAuthMgr.updateAll();

In actual projects, users can use PDFViewer.getCurrentPDFDoc (opens new window) to get the current document object and verify whether the current document is open. If the value is null, it means the document is not open.

# Usage scenarios of view annotation permissions

In practical scenarios, different view annotation permissions may need to be set. Currently, there are mainly four types. The following example is based on a pre-created AnnotationAuthorityManager instance.

No permissions

    // Set the view annotation permissions 
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // Set to have no operation permissions for all annotations
        return Promise.resolve([]);
    })

Combined permissions

    const ANNOTATION_PERMISSION = UIExtension.PDFViewCtrl.constants.ANNOTATION_PERMISSION
    // Set the view annotation permissions 
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // Set the permission of all annotations to be able to modify properties and behaviors, and to be able to delete/move/rotate/scale
        return Promise.resolve([ANNOTATION_PERMISSION.adjustable,ANNOTATION_PERMISSION.deletable,ANNOTATION_PERMISSION.modifiable]);
    })

All permissions

    const ANNOTATION_PERMISSION = UIExtension.PDFViewCtrl.constants.ANNOTATION_PERMISSION
    // Set the view annotation permissions 
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // Set to have all the view annotation permissions
        return Promise.resolve([ANNOTATION_PERMISSION.fully]);
    })

Ignorable permissions

    // Set the view annotation permissions 
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // Set the permissions for all annotations to be ignorable
        return null;
    })

# Usage scenarios of interactive annotation permissions

# Example 1: Set the view annotation permissions which does not allow to delete specified annotations

    const pdfViewer = await pdfui.getPDFViewer();
    // Get the AnnotationAuthorityManager manager
    const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
    // Get the annotationRender of a specified attachment type on a specified page
    const fileAnnotRender = pdfViewer.getAnnotRender(0,'name');
    // Get the annotation of a specified attachment type on a specified page
    const fileAnnot = fileAnnotRender.getAnnot();
    const ANNOTATION_PERMISSION = PDFViewCtrl.constants.ANNOTATION_PERMISSION
    // Set the view annotation permissions 
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // Set a specific file annotation to have no permission to be deleted
        if(annot.getObjectNumber()=== fileAnnot.getObjectNumber()){
            return Promise.resolve(Object.keys(ANNOTATION_PERMISSION).filter(per=>per!==ANNOTATION_PERMISSION.deletable && per!==ANNOTATION_PERMISSION.fully));
        }
    })

    // Update the interactive annotation permissions for the specified annotation
    await annotAuthMgr.update(fileAnnot);

After executing the above code, users will not be able to delete the annotation with the specified name. Have no permission to delete the annotation

# Example 2: Set the view annotation permissions to allow editing the callout content

    const pdfViewer = await pdfui.getPDFViewer();
    // Get the AnnotationAuthorityManager manager
    const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
    const ANNOTATION_PERMISSION = PDFViewCtrl.constants.ANNOTATION_PERMISSION
    // Set the view annotation permissions 
    annotAuthMgr.setAnnotPermissionCallback(function(annot) {
        // Set the callout-type annotation to have editing permission.
        if(annot.getIntent()=== 'FreeTextCallout'){
            return Promise.resolve([ANNOTATION_PERMISSION.editable]);
        }
    })

    // Update the interactive annotation permissions for all the annotations
    await annotAuthMgr.updateAll();

After executing the above code, users will be able to edit the FreeText objects with the type of callout. Have permission to eidt the annotation

# Example 3: Validate PDF annotation permissions and view annotation permissions on a custom component

The following code will demonstrate how to validate annotation permission on a newly added custom component.

    var pdfui = new PDFUI({
        // Customize a new component to delete annotations
        fragments: [{
            target: 'hand-tool',
            template: '<xbutton class="fv__ui-toolbar-show-text-button" name="cus-delete-button">button behind of hand-tool</xbutton>',
            action: UIExtension.UIConsts.FRAGMENT_ACTION.AFTER,
            config: [{
                target: 'cus-delete-button',
                callback: PDFViewCtrl.shared.createClass({
                    mounted: function() {
                        this.permissionHandler();
                    },
                    permissionHandler(){
                        const Events = UIExtension.UIEvents;
                        let permissionHandler = async ()=>{
                            const docRender = await pdfui.getPDFDocRender()
                            // Get PDF annotation permissions
                            const userPermission = docRender.getUserPermission().getValue();
                            const {AnnotForm} = UIExtension.PDFViewCtrl.Consts.PDFDocPermission;
                            this.hasAnnotForm = (userPermission & AnnotForm) === AnnotForm;
                            // Whether to disable this component
                            this.component[this.hasAnnotForm?'enable':'disable']();
                        }
                        this.addDestroyHook(
                            pdfui.addViewerEventListener(Events.openFileSuccess,permissionHandler)
                            pdfui.addViewerEventListener(Events.permissionChanged,permissionHandler)
                            pdfui.addViewerEventListener(Events.activeAnnotation,async annotRender=>{
                                // Get the active annotation
                                const annot = annotRender.getAnnot();
                                const pdfViewer = await pdfui.getPDFViewer();
                                // Get AnnotationAuthorityManager manager
                                const annotAuthMgr = pdfViewer.getAnnotAuthorityManager();
                                // Get the view annotation permissions of a specified annotation.
                                const annotPermission = await annotAuthMgr.getPermission(annot);
                                // Get the value which indicates whether the annotation can be deleted
                                const isDeleteAble = annotPermission.isDeletable();
                                // Whether to disable this component
                                this.component[isDeleteAble&&this.hasAnnotForm?'enable':'disable']();
                            })
                        );
                    }
                }, UIExtension.Controller)
            }]
        }]
    });

# Restrictions on view annotation permissions

Currently, the restrictions on view annotation permissions are:

The Redaction Apply function does not support setting interactive annotation permissions.
AnnotationAuthorityManager does not support Form Widgets.

← The Edit Modules in Foxit PDF SDK for Web PDFViewer Multiple Instances →