One of the very first major additions that Datalogics made to PDF Java Toolkit (PDFTJ) was to add the ability to ‘decorate’ pages with page headers, page footers, backgrounds, and watermarks…just like Acrobat did.
Literally just like Acrobat did because one of the goals was to have the page decorations be modifiable in Acrobat. However, this functionality wasn’t built with usage from PDFJT in mind, but to be used with the now defunct PDF Web API. PDFJT was just the tool that made the page decoration service possible. The WebAPI took a JSON form of the configuration file and generated an XML version to be inserted into the PDF via PDFJT.
If you don’t have the WebAPI’s magic code for generating the appropriate XML configation, or an XML file that fell off of the back of a PieceInfo dictionary, the PDFJT interface to the page decoration service leaves something to be desired. It has been something I’ve wanted to address ever since the DecorationService was added to PDFJT. So, I went on a scavenger hunt in the WebAPI codebase for the relevant bits of code to put them together into a PDFJT sample app.
The DecorationService can be used like so if you have an appropriate XML Configuration file to use:
Now HeaderFooterSettings is basically this:
To which I’ve joined the convertToXML routine from the corresponding JSON-marshalling class (Not included)
Which goes on to basically fill a HeaderFooterXML class:
Which extends the decorationXML class:
Note the ‘revisit this’ comment; it’s because of:
Eclipse couldn’t find the commented out import; I found an equivalent import. …and Eclipse complains about that too, but it works.
Moving on, the WatermarkSettings class has different members but is essentially the same as HeaderFooterSettings:
Now, let’s revisit the configuration twiddling we saw earlier:
The PageRange.setPages routine allows you to specify page ranges as a comma-separated string of start-stop ranges where stop can be the keyword ‘last‘.
The Page.setFormat routine allows you to specify one of four page number formats.
The footer (in this case, or header otherwise) could be on the left, center, or right. Or -and this functionality not offered by Acrobat, the last time we checked- inside or outside of facing pages.
But the magic really happens in the HeaderFooterSettings’ ConvertToXML routine where the $page macro is substituted as appropriate.
There is also a $date macro which allows a specifying a few date formats:
I can’t claim credit for originating this code, though I did help the WebAPI team at the time figure some of the pieces of this puzzle. But, I was extremely happy with how easily I was able to adapt their code to work outside of its original context for this sample app. Kudos to them.