Integrating rich media Part 2 (iText 5)

Establishing communication between Flex and PDF

Figure 16.8 shows a series of widget annotations (PDF), and one rich media annotation (Flash). The sentence, "This is the festival program for 2011-10-14", is shown using a read-only text field. The text is updated using a JavaScript method that is triggered by the rich media annotation. The buttons with the different dates call a Rich-MediaExecuteAction that executes an ActionScript method in the Flash application.

The Flex application, in the next listing, is different from the previous example.

Figure 16.8 Communication between PDF and Flash

Listing 16.21 FestivalCalendar2.mxml

You’ll recognize the HTTP service that will get the XML files from http://flex.itext-pdf.org/ and the data grid that visualizes the XML data. You no longer need the combo box and the button, because you’re going to change the data from outside the Flex application.

You import the flash.external.* package O, because you’re going to use the ExternalInterface object. With the addCallback() method ©, you make the ActionScript method getDateInfo() in the Flex application available for external applications. In this method, you call the JavaScript showDate() method that is supposed to be present in the PDF document by using the call() method ©.

The showDate() JavaScript method in the PDF is very simple:

It gets the text field with the name date, and it changes the value of this field so that it corresponds with the date for which the screenings are shown. The first part of this next listing should look familiar.

Listing 16.22 FestivalCalendar2.java

In the second half of the previous listing, you add a series of buttons to the document, creating a RichMediaExecuteAction for each button. The action will be triggered on the rich media annotation for which you pass the indirect reference. You also pass a RichMediaCommand.

The name of the action is a PDF string that corresponds to the string you used as the parameter of the ExternalInterface .addCallback() method in the Flex application. The argument can be a PdfString, PdfNumber, PdfBoolean, or PdfArray containing those objects.

You also add a text field named date. When you click one of the PDF buttons, the getDateInfo() method will be called, an XML file containing screenings will be fetched from the internet, filling the data grid, and the Flex application will trigger the showDate() JavaScript method to change the value of the date field.

Although this is a very simple example, the techniques that are used can apply to many different types of applications. You could use these techniques to integrate fancy Flash buttons that trigger functions in a PDF file, or you could embed a Flex application to establish client-server communication to retrieve the most recent data. But don’t forget that this functionality is very new: it only works with the most recent versions of Adobe Reader!

Summary

In this final chapter, we’ve looked at different kinds of PDF streams. We started with streams that hold an image or a font and looked at the way iText creates low-level objects that are responsible for writing such a stream to the OutputStream. You also learned how to replace such a stream.

Then we moved on to a type of annotation we encountered in chapter 7: a file attachment annotation. You discovered that there’s a difference between file attachments that are added as annotations, and file attachments that are stored at the document level as embedded files. This difference matters if you want to extract files from a PDF document. Files that are embedded at the document level can be organized into a portable collection, aka a portfolio.

Finally, we discussed multimedia files. You added annotations containing a movie file and a 3D stream, and you also used a very new type of annotation that isn’t part of IS0-32000 yet.

With a rich media annotation, you were able to integrate a Flash application into a PDF document, and establish communication between the ActionScript in the Flash application and the JavaScript in the PDF document. Those were the last examples of this topic.

WHAT YOU’VE LEARNED FROM THIS TOPIC

Let’s return to the first image in chapter 1 and quickly review everything you’ve learned. Figure 16.9 shows three main areas.

CREATING PDFS

Chapter 1 provided a short introduction. In chapters 2 and 4 you learned to create PDF documents from scratch using high-level objects. You did the same using low-level functionality in chapters 3 and 5. These first five chapters formed part one of the topic.

Essential skills concerning PDF creation were explained in part three. In chapter 9, you learned to create documents on the fly from a web application. We focused on color and images in chapter 10, and on fonts in chapter 11. Chapter 12 was about encrypting and signing documents.

For advanced users, there’s also part four, which explains the inner workings of iText and PDF. Chapter 14 will remain especially interesting as a reference for developers who frequently need to add content to a document using low-level methods.

Most of the PDF files in this topic were generated using data from a database, but in some cases you converted an XML or an HTML file to PDF. For instance in chapter 9, we talked about using the HTMLWorker class to convert HTML snippets; in chapter 11 you converted an XML file containing the word "peace" in many different languages into a PDF document.

Figure 16.9 Overview of the PDF functionality that was covered

On occasion, we looked at creating a PDF document manually, using Open Office rather than using iText, such as in chapter 6. In chapter 8, you used Adobe Acrobat and LiveCycle Designer. These files were created for the purpose of updating them, and that takes us from the Read block in figure 16.9 to the Update block.

UPDATING PDFS

Part two of this topic was titled "Manipulating existing PDF documents." Chapter 6 presented an overview of all the PDF manipulation classes available in iText. You always needed a PdfReader instance to access an existing document. You learned how to split and merge PDF documents with PdfCopy, PdfSmartCopy, PdfCopyFields, and even using PdfImportedPage objects, but the class you used the most was PdfStamper, which was initially written to stamp extra information on an existing document.

In chapter 7, you used PdfStamper to add different types of annotations. This functionality is also useful when creating a document from scratch; for instance, to add links that allow the end user to navigate from one page to another, or from one document to another. Along the way, we talked about bookmarks, actions, and destinations.

Chapter 8 was dedicated entirely to forms: you worked with forms built using the AcroForm technology, and with XFA forms. iText has almost complete support for AcroForms, but as soon as you have a form involving the XML Forms Architecture, the possibilities are limited. For instance, iText can’t flatten an XFA form (yet).

Signing and encrypting existing PDF documents was discussed in chapter 12. Converting a PDF document to another format turned out to be very difficult, but in some cases, you can extract an XML version of the complete document, or extract plain text from a page.

READING PDFS

iText isn’t a PDF viewer, nor can iText be used to print a PDF, but the PdfReader class can give you access to the objects that form a PDF document. The different types of objects that are defined in the PDF specification were listed in chapter 13, where you also had a closer look at the root object of a PDF document.

Chapter 14 dealt with the imaging system and the way the content of a page in a PDF document is organized. We continued studying the content stream of a page in chapter 15, looking for ways to add structure. You found out that a PDF can be read out loud if marked content has been added to improve the accessibility of the document. You also learned how to convert a PDF to XML if the PDF was tagged and contains a structure tree. At the end of the chapter, we made a fair attempt at parsing the content of a page to plain text.

Finally, in chapter 16 you learned more about streams. You even wrote a Flex application for use in a PDF document.

This isn’t the first topic I’ve written, and based on my previous experience, I know that one can never have enough documentation. But with this topic, you have a comprehensible overview of what is possible with PDF in general—the different topics listed in figure 16.9—and with iText in particular—the topics marked with the iText logo.

Sure, writing a topic is a lot of work, but I also had a lot of fun writing new material for this second edition: creating the movie database, making my first dynamic PDF using LiveCycle Designer, learning Flex for the sole purpose of creating a PDF containing a rich media annotation, and inventing many other new examples that weren’t in the first edition.

I hope you’ve enjoyed reading this topic as much as I enjoyed writing it.