Hyperlinks

Hyperlinks

Hyperlinks are quite useful in PDF documents. Whether you are linking the entries of a TOC to the corresponding chapter, or a piece of information to a corresponding URL in wikipedia. Linking text enriches the content, and makes it more usable.

PDF (and PDFBox) supports hyperlinks, but the PDF standard has no notion of marked up text, but the more general and abstract idea of annotated areas: You can describe some area in the document by coordinates, and add some metadata telling the PDF reader what to do with that area. That's quite powerful. You can do highlighting and all kinds of actions with that, and totally independant of the content, just by describing an area. So if you want to establish a link, you have to create an annotation which references an area in the document (means: you need to know the coordinates of the text you want to use as the link), add some decoration, and finally set up an action that opens that URL... this ain't no fun :-( PDFBox-Layout eases this burden for you:

Document document = new Document();

Paragraph paragraph = new Paragraph();
paragraph.addText("This is a link to ", 18f,
    PDType1Font.HELVETICA);
 
// create a hyperlink annotation
HyperlinkAnnotation hyperlink = 
   new HyperlinkAnnotation("https://github.com/ralfstuckert/pdfbox-layout", 
                           LinkStyle.ul);
                           
// create styled text annotated with the hyperlink
AnnotatedStyledText styledText = 
   new AnnotatedStyledText("PDFBox-Layout", 18f,
   PDType1Font.HELVETICA, Color.black,
   Collections.singleton(hyperlink));
paragraph.add(styledText);

document.add(paragraph);

final OutputStream outputStream = new FileOutputStream("link.pdf");
document.save(outputStream);

You just say what you want: add a hyperlink to the given text. And all this odd area marking boilerplate code is handled by PDFBox-Layout. And as always, things are a lot easier using markup:

Document document = new Document();

Paragraph paragraph = new Paragraph();
paragraph.addMarkup(
   "This is a link to {link[https://github.com/ralfstuckert/pdfbox-layout]}PDFBox-Layout{link}", 
   18f, BaseFont.Helvetica);
document.add(paragraph);

final OutputStream outputStream = new FileOutputStream("link.pdf");
document.save(outputStream);

We just markup the text with the hyperlink URL and that's it :-)

So now we can do external URLs, what about links into the document itself? Let's take the example Links.java. In order to link to some point in the document we have to add an anchor to this position. After that we can link to that anchor using the anchors name:

paragraph0.addMarkup(
   "And here comes a link to an internal anchor name {color:#ff5000}{link[#hello]}hello{link}{color:#000000}.\n\n", 
   11, BaseFont.Times);

...
paragraph4.addMarkup(
   "\n\n{anchor:hello}Here{anchor} comes the internal anchor named *hello*\n\n", 
   15, BaseFont.Courier);

So we define an anchor {anchor:hello}Here{anchor} somewhere in the document with the logical name hello. This anchor name is used in the link prefixed with a hash to indicate an internal link {link[#hello]}hello{link}. See the example PDF (links.pdf) for the results. See more details and options in the Markup page.