Embedded Files and PDF Portfolio Collections

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 automatically detects and shows embedded files via EmbeddedFilesViewController, which is part of the default controller group that includes outlines, bookmarks, and annotations. The embedded files group is only visible if the document contains embedded files.

Embedded files can be accessed via a document’s allEmbeddedFiles property or be attached to a FileAnnotation object. The EmbeddedFile object abstracts these files and allows you to copy them to disk by calling fileURLWithError().

PSPDFKit 7.6 for iOS adds the ability to embed files using FileAnnotation and EmbeddedFile. Take a look at the File Annotations with Embedded Files section of the Programmatically Creating Annotations guide, along with AddFileAnnotationProgrammaticallyExample 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.

Preview and Open Embedded Files

You can preview file attachments directly in PSPDFKit.

You can then open a copy in third-party applications or (on iOS) in Apple’s Files app by using the share action.

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
// Create `Document`.
let document = Document(url: documentURL)

// Create the URL of the appearance stream that uses a PDF file.
let samplesURL = Bundle.main.resourceURL!.appendingPathComponent("Samples")
let embeddedFileURL = samplesURL.appendingPathComponent("Monthly Budget.xlsx")

// Create a new file annotation and set its properties.
let fileAnnotation = FileAnnotation()
fileAnnotation.pageIndex = 0
fileAnnotation.iconName = .graph
fileAnnotation.color = .blue
fileAnnotation.boundingBox = CGRect(x: 500, y: 250, width: 32, height: 32)

// Create an embedded file and add it to the file annotation.
let embeddedFile = EmbeddedFile(fileURL: embeddedFileURL, fileDescription: "Monthly Budget")
fileAnnotation.embeddedFile = embeddedFile

// Add the newly created annotation to the document.
document.add(annotations: [fileAnnotation])
Copy
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
// Create `PSPDFDocument`.
PSPDFDocument *document = [[PSPDFDocument alloc] initWithURL:documentURL];

// Create the URL of the appearance stream that uses a PDF file.
NSURL *samplesURL = [NSBundle.mainBundle.resourceURL URLByAppendingPathComponent:@"Samples"];
NSURL *embeddedFileURL = [samplesURL URLByAppendingPathComponent:@"Monthly Budget.xlsx"];

// Create a new file annotation and set its properties.
PSPDFFileAnnotation *fileAnnotation = [[PSPDFFileAnnotation alloc] init];
fileAnnotation.pageIndex = 0;
fileAnnotation.iconName = PSPDFFileIconNameGraph;
fileAnnotation.color = UIColor.blueColor;
fileAnnotation.boundingBox = CGRectMake(500.0, 250.0, 32.0, 32.0);

// Create an embedded file and add it to the file annotation.
PSPDFEmbeddedFile *embeddedFile = [[PSPDFEmbeddedFile alloc] initWithFileURL:embeddedFileURL fileDescription:@"Monthly Budget"];
fileAnnotation.embeddedFile = embeddedFile;
[document addAnnotations:@[fileAnnotation] options:nil];

To learn more about how to programmatically create file annotations with embedded files, check out AddFileAnnotationProgrammaticallyExample 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. According to the PDF Reference 1.7 (12.3.5 Collections, page 370):

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 packages have been improved upon to become PDF Portfolios in Acrobat 9. In most cases, portfolios use a Flash-based interface which 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.