Foxit Developer

Bookmark API Migration Guide ​

This guide helps you migrate from legacy bookmark APIs to the current release. From version 10.0.0, bookmark APIs were refactored for stronger capabilities and better performance. The sections below list deprecated APIs and their replacements.

Confirm which API version you use ​

If your application was built before 10.0.0, after upgrading to 10.0.0 or later search your code for bookmark API usage and check layout templates for legacy bookmark components. Deprecated APIs and components are listed below.

Deprecated APIs ​

The following bookmark APIs were removed and replaced as shown:

Legacy APIDescriptionReplacement API
PDFDoc.getRootBookmarkReturns the bookmark root and loads all bookmarks at onceBookmarkDataService.getFirstLevelBookmarks
PDFDoc.createRootBookmarkCreates bookmark root; the new version creates the root automaticallyNone
PDFBookmark.insertBookmarkInserts a node at the specified positionBookmarkDataService.addBookmark, BookmarkUIService.addBookmark
PDFBookmark.setPropertyUpdates bookmark node propertiesBookmarkDataService.renameBookmark, BookmarkDataService.setColor, BookmarkDataService.setFontStyle, BookmarkDataService.setDestination, BookmarkUIService.renameBookmark, BookmarkUIService.setColor, BookmarkUIService.setFontStyle, BookmarkUIService.setDestination
PDFBookmark.removeDeletes a bookmark nodeBookmarkDataService.deleteBookmark, BookmarkUIService.deleteBookmark
PDF.constant.DataEvents.bookmarkAddedFired when a bookmark is addedBookmarkDataService.onBookmarkAdded
PDF.constant.DataEvents.bookmarkUpdatedFired when a bookmark is updatedBookmarkDataService.onBookmarkPropertiesUpdated
PDF.constant.DataEvents.bookmarkRemovedFired when a bookmark is deletedBookmarkDataService.onBookmarkDeleted

Deprecated UIExtension bookmark components and replacements:

Legacy componentDescriptionReplacement
<bookmark-sidebar-panel>Sidebar bookmark panel<bookmark-v2:sidebar-panel>
<bookmark-contextmenu>Bookmark context menu<bookmark-v2:bookmark-contextmenu>

After replacing legacy components, previously registered bookmark events will not fire. Update event registration as shown in the examples below.

For custom bookmark UI, see Customize bookmarks.

Examples ​

The examples below show how to replace legacy bookmark APIs and highlight differences between versions.

Example 1 — Listen for bookmark added events ​

This example listens for bookmark added events and updates properties via BookmarkDataService.

:::demo [vanilla]

html

<html>
<div id="pdf-ui"></div>
</html>
<style>
    html {
        overflow: hidden;
    }

    body {
        height: 100vh;
    }

    #pdf-ui {
        position: relative;
        top: 50px;
    }
</style>

<script>
    const libPath = window.top.location.origin + '/lib';
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: '#pdf-ui',
        appearance: UIExtension.appearances.adaptive,
        addons: []
    });

    pdfui.getBookmarkDataService().then(bookmarkDataService => {
        bookmarkDataService.onBookmarkAdded((event) => {
            bookmarkDataService.setColor(event.bookmarkId, '#FF0000');
            bookmarkDataService.setFontStyle(event.bookmarkId, {
                bold: true,
                italic: true
            });
        })
    })
</script>
json
{
  "iframeOptions": {
    "style": "height: 500px"
  }
}

:::

Run the example, open a document, and add a bookmark from the bookmark panel. The new bookmark should be red, bold, and italic.

For 9.* and earlier, register bookmark events as follows:

js
pdfui.addViewerEventListener(PDFViewCtrl.ViewerEvents.bookmarkAdded, bookmark => {
    // Here operates the bookmark object
})

Example 2 — Access bookmark tree nodes ​

In 9.* and earlier, all bookmarks loaded into memory and were inserted into the DOM at once, which was slow or sluggish for large trees. After the refactor, loading and rendering depend on visible bookmarks, so performance improves. Bookmarks render through TreeComponent, which also supports customization. The example below gets tree nodes and changes node styles:

:::demo [vanilla]

html

<html>
<div id="pdf-ui"></div>
</html>
<style>
    html {
        overflow: hidden;
    }

    body {
        height: 100vh;
    }

    #pdf-ui {
        position: relative;
        top: 50px;
    }
</style>

<script>
    const libPath = window.top.location.origin + '/lib';
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: '#pdf-ui',
        appearance: UIExtension.appearances.adaptive,
        addons: []
    });

    (async () => {
        const rootComponent = await pdfui.getRootComponent();
        const bookmarkTreeComponent = rootComponent.querySelector('@bookmark-v2:bookmark-tree');
        const treeComponent = bookmarkTreeComponent.getTree()
        treeComponent.on('create-tree-node', treeNode => {
            const titleElement = treeNode.element.querySelector('.fv__ui-tree-node-title');
            titleElement.style.cssText += 'font-family: system-ui, --apple-system, BlinkMacSystemFont;';
        })
    })()

</script>
json
{
  "iframeOptions": {
    "style": "height: 500px"
  }
}

:::

Unlike the legacy version, you cannot querySelector all bookmark DOM nodes after load. In the new version, listen for the create-tree-node event to access nodes.

Example 3 — Undo/redo support ​

Version 10.0.0 adds BookmarkUIService, available when your app uses UIExtension. It mirrors BookmarkDataService but supports undo/redo.

:::demo [vanilla]

html

<html>
<div id="pdf-ui"></div>
</html>
<style>
    html {
        overflow: hidden;
    }

    body {
        height: 100vh;
    }

    #pdf-ui {
        position: relative;
        top: 50px;
    }
</style>

<script>
    const libPath = window.top.location.origin + '/lib';
    const pdfui = new UIExtension.PDFUI({
        viewerOptions: {
            libPath: libPath,
            jr: {
                licenseSN: licenseSN,
                licenseKey: licenseKey
            }
        },
        renderTo: '#pdf-ui',
        appearance: UIExtension.appearances.adaptive,
        addons: [
            libPath + '/uix-addons/undo-redo'
        ]
    });

    (async () => {
        // Create a custom menu item component.
        class HighlightBookmarkContextMenuItem extends UIExtension.SeniorComponentFactory.createSuperClass({
            // Listen to the click event through the @on.click directive.
            template: `<contextmenu-item @on.click="$component.onClick()">Highlight it</contextmenu-item>`
        }) {
            static getName() {
                return 'highlight-bookmark-contextmenu-item';
            }

            async onClick() {
                const treeNode = this.parent.getCurrentTarget();
                const nodeData = treeNode.getData();
                const bookmarkData = nodeData.data;
                const bookmarkId = bookmarkData.id;
                const bookmarkUIService = pdfui.getBookmarkUIService();
                await bookmarkUIService.setColor(bookmarkId, '#FF0000', bookmarkData.color);
            }
        }

        const module = UIExtension.modular.module('custom', []);
        module.registerComponent(HighlightBookmarkContextMenuItem);
        const rootComponent = await pdfui.getRootComponent();
        // Get the bookmark contextmenu instance.
        const bookmarkContextMenu = rootComponent.querySelector('@bookmark-v2:bookmark-contextmenu');
        // Insert a custom menu item at the end of the bookmark contextmenu.
        bookmarkContextMenu.append('<custom:highlight-bookmark-contextmenu-item>');
    })()

</script>
json
{
  "iframeOptions": {
    "style": "height: 500px"
  }
}

:::

This example appends a custom item to the bookmark context menu. Clicking it sets the selected bookmark to red. Use Ctrl+Z / Ctrl+Y to undo/redo. To enable undo/redo, add libPath + '/uix-addons/undo-redo' to addons when initializing PDFUI, or use addons: libPath + '/uix-addons/allInOne.js' to load all addons.