Beyond Acrobat: Adding Annotations to a Layer using the Datalogics PDF Java Toolkit

Beyond Acrobat: Adding Annotations to a Layer using the Datalogics PDF Java Toolkit

Sample of the Week:

One of the coolest aspects of Adobe Acrobat and Reader is the fact that they will display PDF files that contain features that are in the specification but that Acrobat isn’t even capable of creating on it’s own… that’s how thoroughly the application is developed. As part of my “Beyond Acrobat” series, this article discusses the little known fact that in addition to page content, links, comments, movies, 3D models… basically any of the PDF annotation objects can be assigned to an Optional Content Group, or “Layers”, as they’re called in the Acrobat user interface. Using the Datalogics PDF Java Toolkit, developers can create PDF files that simply cannot be created in Acrobat alone but display perfectly well. This opens up a world of possibilities but let’s look at one in particular.

As PDF becomes more and more broadly supported and viewing PDF files becomes more and more integrated into operating systems and browsers, guaranteeing a consistent experience of an interactive PDF becomes more and more of an issue. Some PDF viewers run some JavaScript, some don’t at all. Some viewers allow you to fill in forms, some don’t, and then some do but then corrupt the scripts within the form, get the appearances wrong, don’t render barcodes, or otherwise break the PDF file. There are some really obnoxious viewers out there that do really terrible things to perfectly functional PDF files.


Almost every week I get a request from a large corporation that has decided to standardize on PDF forms or some other kind of interactive PDF file that requires the use of Adobe Reader rather than one of the less capable PDF viewers available. The IT groups in these corporations want to know how to force a user to open the PDF file in one of the Adobe viewers.

The short answer is… you can’t.

However, you can construct a PDF file that will warn users if they are not using an Adobe viewer and just simply work if they are. You’d want to create some sort of warning text or graphic with a link to download the Adobe Reader but you’d want this to be hidden if the user is already using the right tools. There are a few things to keep in mind though.

  • You can’t use JavaScript to detect if the PDF file is being displayed in an Adobe viewer and if not, do something. JavaScript doesn’t run in all PDF viewers so you need to set the default state of the file to appear the way you want it to when it is not being viewed in an Adobe tool.
  • The most obvious choice for the warning and link would be a button field. Button fields can contain a graphic or text or both and can be easily hidden and shown through JavaScript. However, the unfortunate fact is that button fields will render differently in different viewers and button actions and events are inconsistently supported across PDF viewers.
  • URL links in PDF tend to be well supported in even the worst of the viewers currently available. I’m not sure why that’s the case exactly but I’ll take it. Unfortunately, links can’t be hidden or shown. Even an invisible link over a blank area of the page will still have a hit area. You don’t want someone accidentally launching their browser to the Reader Download page just because their mouse wandered over a link.

So… this all leaves us kind of stuck… unless you have a way of adding a link to a layer that can be toggled on and off using JavaScript and based on something specific to the Adobe viewers.

The Gist referenced in this article does exactly that. We’ll use the official Adobe “Get Adobe Acrobat Reader DC” web button as our graphic but we’ll put it on a layer. Then we’ll add a link to the Reader download page and associate that link with the layer as well. We set both of these to be visible by default and then add some JavaScript that will run when the file opens. If the JavaScript runs and detects the presence of the Adobe Search plugin, we know we’re in an Adobe Desktop viewer and can safely hide the layer.

We start by reading in the input PDF file and the image we want to use as the warning graphic and turn it into a PDFXObjectForm so we can add it to the page.

Then we create an Optional Content Group. Optional content refers to sub-clauses of content in a PDF document that can be selectively viewed or hidden. Again, in the Acrobat UI, these are called Layers.

With the layer created, we then simply associate the PDFXObjectForm of our graphic with the new layer and then apply it to the page at the coordinates we want it to appear.

Then we add the link using the same location as the graphic also associating it with the new layer (highlighted).

Finally, we add the JavaScript that is used to hide the layer if the right conditions are met.

Try opening the resulting file in different PDF viewers, you should have the same experience in all non-Adobe viewers, but the objects associated with the layer will be hidden when Adobe Reader or Acrobat is used.

10 thoughts on “Beyond Acrobat: Adding Annotations to a Layer using the Datalogics PDF Java Toolkit

    1. Thanks czart, adding an example of the output is a good idea; I’ll need to start doing that for all of my new posts. For this post, I added a link to the output PDF in the last paragraph. Look for the link over “resulting file”.

  1. In my testing of the resulting file with both Acrobat and Reader 10 and 11 this annotation does not function correctly. In Acrobat and Reader 10 the cursor shows the annotation to be active even when the layer is disabled and the annotation is not visible. Clicking inverts the annotation and executes the link action is in fact active. In Acrobat and Reader 11 the cursor behavior is correct, showing the annotation as disabled when it is not visible, but clicking when not visible still inverts the annotation and executes the link action.

    1. Alan:

      Thanks for your due diligence; I typically don’t test on earlier versions. I’m actually seeing the same behavior as you are. The file does work correctly in Acrobat and Reader DC though. I’m guessing it also works properly in version 9. That’s where I first noticed you could attach annotations to layers.


      1. I just installed Reader DC. For me it also misbehaves in the same manner that Reader 10 does – the cursor indicates the link annotation is active even when it is not visible. A colleague tested Acrobat DC and found the same behavior.

        What is really interesting is that I have a sample PDF made with an older version of our software that has layered link annotations that work correctly in 10, 11 and DC. I had been unsuccessfully attempting to figure out why as PDFs made from the current version of our software have the same problem your PDF has. Unfortunately that PDF is from a customer and I cannot share it. I’m to get one I can share. I have a thread on the Adobe forums:

  2. Our testing reveals that the problem of link annotations being active when their OC is disabled seems to be restricted to when all layers referenced by any link annotation are disabled. If only a subset is disabled the links work as expected.

Leave a Reply

Your email address will not be published.