PDFOne (for Java)
Create, edit, view, print & enhance PDF documents and forms in Java SE/EE

Compatibility

J2SE J2EE Windows Linux Mac (OS X)

Home » Newsletter » April 2008

By Santhanam L.

Bookmarks in a PDF document offer an interactive way for users to navigate to different parts of the document. When displayed in the bookmark panel of a viewer application such as Adobe® Reader, bookmarks in a PDF document can provide a visual representation of the table of contents.

In this part of our PDFOne Java series, we will see how to add, edit, and delete PDF bookmarks. We will also see how to use bookmarks for others actions such as making them open website URLs in a browser window or display a Javascript alert message.

In PDFOne Java, a bookmark is represented by the PdfBookmark class. A PdfBookmark object cannot be created with a normal constructor. We can however

1. add it as a child of
2. insert it before
3. insert it after

an existing bookmark.

Creating PDF Bookmarks

In creation mode, you need to first access the root bookmark, which is a hidden bookmark, using the PdfDocument.getBookmarkRoot() method. This method returns the root bookmark and you can use the method PdfDocument.addBookmark(String title, PdfBookmark parent, int pageNo) to add all normal (visible) bookmarks under the root.

Apart from adding a bookmark under a specified parent, the method also returns the new bookmark object. We can then use this bookmark object to add other new bookmarks above or below or under it, as shown in the code snippet below.

// Create a blank document
PdfDocument document = new PdfDocument();

// Set the document to display the bookmark
// panel of viewer application by default
document.setPageMode(PdfPageMode.USEOUTLINES);

// Create three pages
PdfPage page1 = new PdfPage();
PdfPage page2 = new PdfPage();
PdfPage page3 = new PdfPage();

// Write identifying text identifying the pages
page1.writeText("This is first page. ");
page2.writeText("This is the middle page. ");
page3.writeText("This is the last page. ");

// Add the pages to the document
document.add(page1);
document.add(page2);
document.add(page3);

// Obtain root bookmark
PdfBookmark bmRoot = document.getBookmarkRoot();

// Create a branch of bookmarks under the root
PdfBookmark bm1 = 
	document.addBookmark("Page 1", bmRoot, 1);
PdfBookmark bm11 = 
	document.addBookmark("Page 2", bm1, 2);
document.addBookmark("Page 3", bm11, 3);

// Add a second bookmark under the root
PdfBookmark bm3 = bm1.addNext("Page 3", 3);

// Add a third bookmark under the root
bm3.addPrevious("Page 2", 2);

// Set the document to be displayed after
// it is written to
document.setOpenAfterSave(true);

// Write the document to disk
document.save("bookmark_doc1.pdf");

// Close all I/O streams 
document.close();

Deleting PDF Bookmarks

If we need to delete bookmarks in an existing document, we need to access the first bookmark in the document using the PdfDocument.getFirstBookmark() method. After we do that, we can use the following methods from the PdfBookmark to parse the document tree.

PdfBookmark Method	Purpose
getNext()	Get the next bookmark in that level.
getPrevious()	Get the previous bookmark in that level.
getFirstChild()	Get the first child bookmark. (There can be multiple child bookmarks.)
getParentNode()	Get the parent bookmark (There can be only one paernt.)

If we are able to parse the bookmark tree, then we can use the following methods to delete bookmarks. Here, we need to bear in mind that we cannot destroy a self-destroy a bookmark nor have a parent bookmark deleted using a child bookmark.

PdfBookmark Method	Purpose
removeNext()	Remove the next bookmark in that level.
removePrevious()	Remove the previous bookmark in that level.
removeFirstChild()	Delete the first child bookmark.

The code snippet below shows how to delete bookmarks.

// Create a document with bookmarks
createPDFBookmarks(false);

// Read the document
PdfDocument document = new PdfDocument();
document.load("bookmark_doc1.pdf");

// Obtain the first visible bookmark
// in the document
PdfBookmark bm1 = document.getFirstBookmark();

// Delete children bookmarks of the first bookmark
PdfBookmark bm11 = bm1.getFirstChild();
bm11.removeFirstchild();
bm1.removeFirstchild();

// Obtain the third bookmark, which comes
// after the second bookmark
PdfBookmark bm2 = bm1.getNext();

// Delete third bookmark under root
bm2.removeNext();

// Delete the first bookmark under root
bm2.removePrevious();

// Delete the second bookmark, which is the
// only bookmark left in the document
(document.getBookmarkRoot()).removeFirstchild();

document.setOpenAfterSave(true);

// Write document to file
document.save();
document.close();

Editing PDF Bookmarks

With individual bookmarks, we can change their text, color, and style with which they are displayed in the bookmark panel.

Apart from setting bookmarks to navigate to specific pages, they can also be used for several other things such as to execute JavaScript, open a website URL in a browser window, open a "New message" with a specified "To" email address, or execute "named actions."

// Create a document with bookmarks
createPDFBookmarks(false);

// Read the document
PdfDocument document = new PdfDocument();
document.load("bookmark_doc1.pdf");

// Obtain the first bookmark under root
PdfBookmark bm1 = document.getFirstBookmark();
// Set its color of the first bookmark
bm1.setColor(Color.RED);

// Obtain the second bookmark under root
PdfBookmark bm2 = bm1.getNext();
// Set its text style to bold and italic
bm2.setStyle(PdfBookmark.BOLD + PdfBookmark.ITALIC);

// Obtain the child of the first bookmark under root
PdfBookmark bm11 = bm1.getFirstChild();
// Obtain the grandchild of the first bookmark under root
PdfBookmark bm111 = bm11.getFirstChild();
// Change the text displayed by it
bm111.setTitle("This bookmark is buried deep.");
// Obtain the parent of the above bookmark (child
// of the first bookmark under parent - same as bm11),
// and set its text style to bold
(bm111.getParentNode()).setStyle(PdfBookmark.BOLD);

// Obtain the last bookmark
PdfBookmark bm3 = bm2.getNext();

// Add a bookmark after the last bookmark
// and set it to perform a "named" action
PdfBookmark bm4 = 
	bm3.addNext(PdfAction.NAMED_LASTPAGE,
		    "Go to last page");

// Add a bookmark that after the above bookmark
// and set it to open the Gnostice website
// in a browser window
PdfBookmark bm6 =
	bm4.addNext("Go to www.gnostice.com",
		    "www.gnostice.com",
		    PdfAction.URI);

// Add a bookmark before the above bookmark
// and set it to execute a Javascript script
bm6.addPrevious("Need a welcome?",
		"app.alert(\"Hello, world!\");",
		PdfAction.JAVASCRIPT);

document.setOpenAfterSave(true);

// Write document to file
document.save("bookmark_doc3.pdf");
document.close();