Embedded Files and PDF Portfolio Collections

Embedded Files

PDF 1.4 added support for embedded files, allowing objects to be embedded into any PDF — this includes deep nesting (e.g. a PDF can contain a PDF which contains a PDF which contains a DOCX file). Via the GoToE action, links that link to embedded files inside the PDF can be created.

PSPDFKit supports two ways of attaching files to a document:

  1. A file can be attached to a FileAnnotation. The file annotation is represented by a small icon on the page (similar to a note annotation) and provides access methods to the file.

  2. Files can be attached directly to the PdfDocument. These files aren’t visible on the document and can be accessed using the EmbeddedFilesProvider, which can be retrieved by calling PdfDocument#getEmbeddedFilesProvider().

💡Tip: The EmbeddedFilesProvider gives access to all embedded files in a document, independent of whether they are attached to FileAnnotations or directly to the document.

PSPDFKit has the ability to create a FileAnnotation with embedded files. Take a look at the File Annotations guide and the FileAnnotationCreationExample inside the Catalog app, both of which show how to programmatically create file annotations with embedded files.

See also: How to Embed Files Using File Annotations on our blog.

Programmatically Create a File Annotation with an Embedded File

You can create a file annotation with an embedded file using the URL of any file. Here’s how this looks in code:

Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
// Open PdfDocument.
val document = PdfDocumentLoader.openDocument(context, uri)

// Create an embedded file source serving file data from assets.
val embeddedFileSource = EmbeddedFileSource(
    AssetDataProvider("Monthly Budget"),
    "Monthly Budget.xlsx",
    "Monthly Budget"
)

// Create a file annotation instance.
val fileAnnotation = FileAnnotation(
    // Page index 0.
    0,
    // Page rectangle (in PDF coordinates).
    RectF(500f, 250f, 532f, 218f),
    // Use the created embedded file source.
    embeddedFileSource
)
fileAnnotation.iconName = FileAnnotation.GRAPH
fileAnnotation.color = Color.BLUE

// Add the newly created file annotation to the document.
document.annotationProvider.addAnnotationToPage(fileAnnotation)

To learn more about how to programmatically create file annotations with embedded files, check out FileAnnotationCreationExample on Android inside the Catalog app.

PDF Portfolio Collections

In PDF 1.7, the term “PDF package” was created to describe a PDF document that contains a collection dictionary:

Beginning with PDF 1.7, PDF documents may specify how a conforming reader’s user interface presents collections of file attachments, where the attachments are related in structure or content. Such a presentation is called a portable collection.

(PDF Reference 1.7, 12.3.5 Collections, Page 370ff)

PDF packages have been improved upon to become PDF Portfolios in Acrobat 9. In most cases, portfolios use a Flash-based interface that was deprecated in PDF 2.0 and is unsupported. Adobe Flash itself does not work on mobile devices and is deprecated as a whole.

PSPDFKit has no special support for packages and portfolios other than fully exposing the embedded files.