Hack 54 Add Attachments to Your PDF (Even Without Acrobat)

Include live data that your readers can unpack and use.

PDF provides a convenient package for your document. A typical PDF contains fonts, images, page streams, annotations, and metadata. It turns out that you can pack anything into a PDF file, even the source document used to create the PDF! These attachments enjoy the benefits of PDF features such as compression, encryption, and digital signatures. Attachments also enable you to provide your readers with document data, such as tables, in a native file format that they can easily use. People often ask, [Hack #7]. Attach your document data as HTML or Excel files and give your readers exactly what they need.

This hack explains how to attach files to your PDF. [Hack #55] goes on to describe how to quickly extract your document's tables for PDF attachment.

5.5.1 Page Attachments Versus Document Attachments

You can attach a file to a particular PDF page, where it is visible as an icon. Or, you can attach a file to the PDF document so that it keeps a lower profile. After encrypting your PDF, document attachments can't be unpacked without the ModifyAnnotations permission [Hack #52] . Page attachments, on the other hand, can be unpacked at any time, regardless of the security permissions you imposed. Of course, the PDF must be opened first, which could require a user password.

5.5.2 Attach Files to a PDF with Acrobat

Attach your file to a PDF page using the Attach File commenting tool. In Acrobat 6, access this tool using the Advanced Commenting toolbar or from the Tools Advanced Commenting Attach menu. In Acrobat 5, access this tool using the Commenting toolbar. The Attach File tool button hides under the Note tool button; click the little down arrow to discover it, as shown in Figure 5-3.

Figure 5-3. Acrobat 6's Attach File paperclip-icon toolbar button and Acrobat 5's hidden Attach File toolbar button, under the Note tool button

Activate the Attach File tool and the cursor becomes a push pin. Click the page where you want the attachment's icon to appear and a file selector dialog opens. Select the file to attach. A properties dialog will open, where you can customize the appearance of your attachment's icon.

As we noted, document attachments are different from page attachments. In Acrobat 6, access document attachments by selecting Document File Attachments . . . . Select Document File Attachments and click Import . . . to add an attachment. In Acrobat 5, select File Document Properties Embedded Data Objects . . . . Click Import . . . to add an attachment.

5.5.3 Attach Files to PDFs with pdftk

Our free pdftk [Hack #79] can attach files to PDF documents and pages.

When attaching files to an existing PDF, call pdftk like so:

pdftk <PDF filename> attach_file <attachment filename> \

[to_page <page number>] output <output filename>

The output filename must be different from the input filename. For example, attach the file data.xls to the first page of the PDF report.pdf like so:

pdftk report.pdf attach_file data.xls to_page 1 output report.page_attachment.pdf

Attach data.xls to report.pdf as a document attachment instead of a page attachment by simply omitting the to_page parameter:

pdftk report.pdf attach_file data.xls output report.doc_attachment.pdf

You can include additional output parameters, too, such as PDF encryption options.

5.5.4 Attachments and Encryption

When you encrypt a PDF, you also encrypt its attachments. The permissions you apply can affect whether users can unpack these attachments. See [Hack #52] for details on how to apply encryption using pdftk.

Once the PDF is open in Acrobat/Reader (which might require a password), any files attached to PDF pages can be unpacked, regardless of the PDF's permissions. This enables you to disable copy/paste features, yet still make select data available to your readers.

Document attachments are more restricted than page attachments. You must grant the ModifyAnnotations permission if you want your readers to be able to unpack and view document attachments.