Bookmarks
Overview
This guide shows how to create, read, change and remove bookmarks in a Word document with Aspose.Words FOSS for Java. A bookmark gives a position or a stretch of text in a Word document a name, so that code can find it again. DocumentBuilder.startBookmark marks the current position in the document as a bookmark start and DocumentBuilder.endBookmark marks it as the bookmark end. The bookmarks of a range are returned by getRange().getBookmarks(), a BookmarkCollection, and each one is a Bookmark with a name and the text it encloses. This page creates a bookmark and reads it, then replaces the enclosed text, saves the document and removes the bookmark. Both examples were compiled and run against the published package on Java 8, 17 and 21.
Prerequisites
| Requirement | Detail |
|---|---|
| Java | 8 or later |
| Dependency | The package from Installation |
| Import | import com.aspose.words.*; |
| Code | The examples are statements. Put them in a method that declares throws Exception. |
Create and Read a Bookmark
Write text with a DocumentBuilder, wrap part of it between startBookmark and endBookmark, and look the bookmark up by name in doc.getRange().getBookmarks(). The run printed the bookmark’s name and its text, and one bookmark in the document.
import com.aspose.words.*;
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Start ");
builder.startBookmark("Intro");
builder.write("the bookmarked text");
builder.endBookmark("Intro");
builder.write(" end.");
Range range = doc.getRange();
BookmarkCollection bookmarks = range.getBookmarks();
Bookmark bookmark = bookmarks.get("Intro");
System.out.println(bookmark.getName() + ": " + bookmark.getText());
System.out.println("Bookmarks in the document: " + bookmarks.getCount());The program printed:
Intro: the bookmarked text
Bookmarks in the document: 1Change the Text, Save, and Remove the Bookmark
Bookmark.setText replaces the text the bookmark encloses. The example fills a bookmark named Customer, saves the document, reloads it and reads the text back. getBookmarks().remove then removes the bookmark by name. Removing a bookmark does not remove its text: the document still read the new text afterwards.
import com.aspose.words.*;
Document doc = new Document();
DocumentBuilder builder = new DocumentBuilder(doc);
builder.write("Dear ");
builder.startBookmark("Customer");
builder.write("customer name");
builder.endBookmark("Customer");
builder.write(", welcome.");
// Replace the text inside the bookmark, then save and reload the document.
doc.getRange().getBookmarks().get("Customer").setText("Acme Corp");
doc.save("welcome.docx");
Document reloaded = new Document("welcome.docx");
System.out.println(reloaded.getText().trim());
// Remove the bookmark; its text stays in the document.
reloaded.getRange().getBookmarks().remove("Customer");
System.out.println("Bookmarks left: " + reloaded.getRange().getBookmarks().getCount());
System.out.println(reloaded.getText().trim());The program printed:
Dear Acme Corp, welcome.
Bookmarks left: 0
Dear Acme Corp, welcome.Tips and Best Practices
- Use names that describe the content, such as Customer, so that the code that fills the bookmark is easy to read.
- Call
endBookmarkwith the same name that was given tostartBookmark. Bookmark.getTextandsetTextwork with the text between the start and the end of the bookmark.
Common Issues
| Issue | Cause | Fix |
|---|---|---|
| The compiler reports cannot find symbol for Document. | The com.aspose.words package is not imported. | Add import com.aspose.words.*;. |
| The compiler reports an unreported exception. | The Document constructors, Document.save and some other methods declare throws Exception. | Declare it on the calling method or catch it. |
| The bookmark is not found by its name. | The name does not match a bookmark in the range, and get then returns null, so a call such as setText on the result throws a NullPointerException. | Check the spelling and that startBookmark and endBookmark used the same name, and test the result for null. |
FAQ
How do I find a bookmark?
Call get with the bookmark name on the BookmarkCollection that getRange().getBookmarks() returns.
Does removing a bookmark delete its text?
No. In the example the text stayed in the document after remove; only the bookmark was removed.
Can I count the bookmarks?
Yes. BookmarkCollection.getCount returns the number of bookmarks in the collection.
API Reference Summary
| Class / Method | Description |
|---|---|
Bookmark | Represents a single bookmark. |
Bookmark.getText() | Gets the text enclosed in the bookmark. |
BookmarkCollection | A collection of Bookmark objects that represent the bookmarks in the specified range. |
DocumentBuilder.startBookmark(name) | Marks the current position in the document as a bookmark start. |
DocumentBuilder.endBookmark(name) | Marks the current position in the document as a bookmark end. |
Related Guides
- Footnotes and Endnotes
- Working with Text
- Find and Replace
- How to Fill a Bookmark in a Word Document in Java (knowledge base)