Sample of the Week:
I recently completed a competitive analysis in which I compared the Datalogics PDF Java Toolkit to other Java based PDF developer tools. You can probably guess that we compare favorably… otherwise I wouldn’t be writing this… but there are two areas that our toolkit seriously excels at – processing JavaScript enabled forms and creating Appearances for annotations and fields. It’s the second one that I’ll be discussing today.
Not to name any names but most of the PDF developer tools available are pretty good these days if you just want to do the simple stuff. A few of them do go the extra mile and try to create appearances for basic form fields. But, as far as I was able to tell, only the Datalogics PDF Java Toolkit will create appearances for all field types including Rich Text fields. It does a great job too, the appearance is nearly identical to the one Acrobat creates on it’s own.
But there’s one little trick to making it work.
A Rich Text field in PDF actually has two values, the XML representation of the Rich Text and a plain text version. The plain text version is a sort of fallback value to accommodate viewers that may not be able to edit Rich Text.
To set the Rich Text value of a field, you just need to read in the XML that represents the Rich Text as a string and then set it.
If you plan on flattening the field or otherwise making it not interactive, that’s it. You’re done. However, if you want end-users to be able to edit the Rich Text field, you also need to set the regular string value of the field.
Now, when I noticed this step was necessary to make the form field interactive, the first thing I did was write a bunch of code to convert the XML string into an XML Document object and then dig around in it to get the text content… and that actually worked… sometimes. In digging around the documentation to discover why it worked and why it didn’t, I discovered the wonderful RichTextHandler class which has a method that does this for you in one line of code… and the returned string works every time.
Setting both of these values properly does two things.
- The AppearanceService class needs the values to match up the right way. The AppearanceService won’t generate a Rich Text appearance if the string value isn’t exactly the same as the raw content of the XML so it’s best to set it when populating a field with Rich Text.
- It allows the field to be interactive in Acrobat. If you only set the Rich Text value and the field doesn’t have a /V key, you will get an appearance generated by the service and the field will appear in the document properly but when you go to edit it, the field goes blank.
Once the Rich Text values are set and the appearance appearance is generated, the field is fully editable in Acrobat and Reader or can be flattened and it will look exactly as it should.
To get started working with PDF, download this Gist and request an evaluation copy of The Datalogics PDF Java Toolkit.
