Three ways to embed files into a PDF using the Apryse SDK

By Roger Dunham | 2024 Nov 15

5 min

Introduction

Copied to clipboard

PDFs are everywhere and quite rightly so – they are an excellent way of transferring information, whether that is to customers, colleagues, government or anyone else, in a consistent portable way.

While often thought of as just being the equivalent of a printed document (albeit with the ability to zoom into parts of the document, or to search for content) they can be much more. For example, they can have other files embedded into them, making a PDF a handy way to keep related content together.

In this short article we will see three ways that you can add a file, or files, to a PDF using the Apryse SDK. We will also see how the PDFs that are created look when viewed in either the desktop app Xodo PDF Studio, or the browser based WebViewer.

In this article we will be using C#, but the Apryse SDK works with many other languages too, including C++, Python, Java, JavaScript, Ruby and PHP.

It’s easy to get started using the SDK – grab yourself a free trial license, then download the version of the file that suits your platform, whether that is Windows, Linux or macOS.

Included in the download is a comprehensive set of samples that illustrate the wide range of functionality that is available. The sample code used in this article is based on (but has some differences to) those samples.

Setting up the project

Copied to clipboard

There is some general house-keeping when using the SDK, you need to Initialize PDFNet (which is the main object for the Apryse SDK library), and call Terminate to free resources when you are finished.

For the three scenarios that we will look at we are going to create a PDF from scratch – using the method CreateSimplePDF (see below). There’s no need to use an empty PDF though, you could use an existing one, but this is a nice way to demonstrate some of the low-level SDK functionality which is available (and it is based on the PDFPackage sample).

Having created the PDF, we will then attach one or more files to it, and save the resulting document.

[STAThread] 
static void Main(string[] args) 
{ 
PDFNet.Initialize(PDFTronLicense.Key); 
try 
{ 
using (PDFDoc doc = new PDFDoc()) 
{ 
CreateSimplePDF (doc); 
doc.Save([Filename],  SDFDoc.SaveOptions.e_compatibility); 
Console.WriteLine("Done."); 
} 
} 
catch (PDFNetException e) 
{ 
Console.WriteLine(e.Message); 
} 
 
 
PDFNet.Terminate(); 
} 
 
static void CreateSimplePDF (PDFDoc doc)  
{ 
// Here we dynamically generate cover page (please see ElementBuilder  
// sample for more extensive coverage of PDF creation API). 
Page page = doc.PageCreate(new Rect(0, 0, 300, 400)); 
 
using (ElementBuilder b = new ElementBuilder()) 
using (ElementWriter w = new ElementWriter()) 
{ 
w.Begin(page);  
Font font = Font.Create(doc, Font.StandardType1Font.e_helvetica); 
w.WriteElement(b.CreateTextBegin(font, 12)); 
Element e = b.CreateTextRun("PDF with Embedded Files"); 
e.SetTextMatrix(1, 0, 0, 1, 50, 96); 
e.GetGState().SetFillColorSpace(ColorSpace.CreateDeviceRGB()); 
e.GetGState().SetFillColor(new ColorPt(1, 0, 0)); 
w.WriteElement(e); 
w.WriteElement(b.CreateTextEnd()); 
w.End(); 
doc.PagePushBack(page); 
} 
 
// Alternatively we could import a PDF page from a template PDF document 
// (for an example please see PDFPage sample project). 
}

OK, we have our app ready to run, so now let’s see how we can attach files.

Option 1: File Attachment Annotations

Copied to clipboard

The PDF specification supports the idea of annotations. Common ones are underlines, text and highlighting.

Figure 1 - Various annotations added to a PDF - in this case using the Apryse Showcase.

However, there are many other types of annotation, including file attachment which, as its name suggests, allows us to add an annotation which is associated with an attached file.

You can add a file attachment annotation to the PDF with just a few lines of code.

static void AddAttachmentAnnotation(PDFDoc doc, string file) 
{ 
var first_page = doc.GetPage(1); 
FileAttachment file_attach = FileAttachment.Create(doc, new Rect(80, 280, 108, 320), file, “Paperclip”); 
file_attach.SetTitle(System.IO.Path.GetFileName(file)); 
first_page.AnnotPushBack(file_attach); 
}

It’s important to note that annotations are associated with a specific page, so we need to specify the page where it will be (in this case page 1). Annotations also have a location on the page where they should be shown. (in this case the annotation is specified as a rectangle with a bottom left location of [80, 280] and a top right location of [108, 320] measured in points, relative to the bottom left of the document).

Coordinate systems in PDF can be confusing so check out the documentation on Getting PDF Coordinates

It’s also possible to add file attachment annotations to a PDF from the UI using WebViewer or Xodo PDF Studio.

Figure 2 - You can try out adding a file attachment annotation with WebViewer using the Apryse Showcase.

Many types of file can be added as a file attachment annotation, and as an example, we will add an XLSX file.

The appearance of the resulting PDF depends on which viewer is used. Some viewers, such as Chrome and Edge, which are based on the pdfium library, don’t show the attachments at all, which is both disappointing and, arguably, a security risk.

Xodo PDF Studio, on the other hand allows you to see the attachment.

Figure 3 - XODO PDF Studio lets you see that an attachment is present and also allows you to open or download it.

It also allows you to Save the attached file, or even open it.

Figure 4 - The XLSX file opened directly from the PDF.

WebViewer also shows that a file attachment annotation is present. While you can download the attachment, you can’t open the file directly (since the app is running in the browser).

Figure 5 - WebViewer shows that a file has been attached.

Option 2: Embedded Files

Copied to clipboard

We saw that a file attachment annotation relates to a specific page. Files can also be attached to the entire document.

There is a little code needed in order to add an attachment using the Apryse SDK. This involves working with the low-level “COS” objects in the PDF. While working at this level can be complex and requires a good knowledge of the PDF specification but gives fine control over the PDF content. In the case of adding an embedded file, though, the process is not difficult.

All that is needed is to create (or get an existing) NameTree object called “EmbeddedFiles” then create a FileSpec object to associate the file with the PDF.

        static void AddAttachment(PDFDoc doc, string file, string desc) 
        { 
            NameTree files = NameTree.Create(doc, "EmbeddedFiles"); 
            FileSpec fs = FileSpec.Create(doc, file, true); 
            byte[] file1_name = System.Text.Encoding.UTF8.GetBytes(file); 
            files.Put(file1_name, fs.GetSDFObj()); 
            fs.GetSDFObj().PutText("Desc", desc); 
        }

As an example, we will add three files to the document – one is a PDF, another is an image and the third is a DOCX file.

AddAttachment(doc, input_path + "numbered.pdf", "My File 1"); 
AddAttachment(doc, input_path + "peppers.jpg", "peppers.jpg"); 
AddAttachment(doc, input_path + "the_rime_of_the_ancient_mariner.docx", "Mariner");

If we save that PDF, then open it in Xodo PDF studio we can now see those files.

Figure 6 - Embedded files shown in Xodo PDF Studio

You can also add or remove attachments directly within Xodo PDF Studio. Once they are there you can save or open them. As an example, we can open the image file in the default image viewer, without the need to download it first.

Figure 7 - Opening an embedded image file directly from within Xodo PDF Studio.

Working with embedded files in WebViewer is a little more complex to describe since it is configuration dependent. If the fullAPI is not enabled, then embedded files won’t be shown (although file attachment annotations will be).

If fullAPI is enabled, then you will be able to see the attached files.

Figure 8 - WebViewer showing the list of embedded files.

Clicking on one of the attached files will cause it to be downloaded, just as we saw with file attachment annotations.

What is the difference between embedded files and file attachment annotations?

Copied to clipboard

It is possible to have both embedded files and file attachment annotations in the same PDF.

File attachment annotations are associated with a specific page, while embedded files are associated with the document as a whole.

Figure 9 - A file with both a file attachment annotation and embedded files.

This means that if you delete a page that contains a file attachment annotation, then the annotation will be removed from the list of attachments, but the other embedded files (that relate to the whole PDF) will remain. Similarly, if you extract a page that contains a file attachment annotation, the extracted PDF will also contain that annotation plus any other attachments that were associated with the file as a whole.

Option 3: Portfolios

Copied to clipboard

PDF Portfolios, also known as “PDF Packages” and “Collections”, are just a special way of treating embedded files. They are particularly useful in legal and AEC sectors to organize multiple documents into a single transferable file. For example, if you have a proposed AEC development, you might include background information, site-location information, CAD drawings and costings into a single PDF portfolio.

Figure 10 - Example of a PDF Portfolio showing the multiple files that it contains.

Under the hood, creating a PDF collection can be as simple as reusing our existing code to embed files, then adding a new object to the PDF called “Collection”.

static void MakePortfolio(PDFDoc doc)  
{ 
Obj collection = doc.GetRoot().FindObj("Collection"); 
if (collection == null) 
{ 
collection = doc.GetRoot().PutDict("Collection"); 
// You could here manipulate any entry in the Collection dictionary.  
// For example, the following line sets the tile mode for initial view mode 
// Please refer to section '2.3.5 Collections' in PDF Reference for details. 
collection.PutName("View", "D"); 
} 
}

If you want to add further files to the portfolio, once it has been created, then you can just call AddAttachment with the new file, in the same way that we did before.

While it’s easy to create a PDF portfolio, viewing them can be disappointing with many non-Apryse tools. Even within the Apryse family there are significant differences in the way that a Portfolio appears depending on whether you are using Xodo PDF Studio or WebViewer.

In Xodo PDF Studio the original PDF is not shown (which is the same behavior as Adobe Acrobat) – instead you just see a list of the embedded files.

Figure 11 - In Xodo PDF Studio, a portfolio just shows the embedded files, which you can download or open.

It is however possible to save or open any of the embedded files.

WebViewer, on the other hand (provided that it has been initialized with the full API and the Portfolio feature is enabled) gives, in my opinion a superior result. It is possible to see both the embedded files, plus the original PDF.

Figure 12 - A portfolio in WebViewer. The initial PDF (which in this case contains a file attachment annotation) is still visible.

In addition to being able to download the attached files, you can open them in a new tab, using the built in viewing support for many file types.

Figure 13 - An embedded file shown opened in a new tab in WebViewer.

This can be taken a step further. By enabling OfficeEditing it is possible to open and edit the DOCX files directly within WebViewer – avoiding the need to download the file and use a separate app.

That really is fantastic functionality!

Next steps

Copied to clipboard

We’ve seen how you can embed files or create portfolios using the Apryse SDK, and how you can then view them in Xodo PDF Studio or WebViewer.

The Apryse tools go much further though, offering PDF editing, measurement, redaction and a host of other features. Why not try things out for yourself. There’s lots of documentation for the SDK, but if you run into any problems, or have any questions then please reach out to us on Discord.