Inserting pages into a PDF with Acrobat JavaScript

Learn how to automate the task of inserting pages from one PDF into another using Acrobat JavaScript.

By Thom Parker – February 12, 2009

 

Scope: Acrobat 5.0 and later
Category: Automation
Skill Level: Intermediate and Advanced
Prerequisites: Basic Acrobat JavaScript Programming

One of the most common document-preparation tasks is inserting pages from one PDF into another PDF. Whether it’s simply appending documents or inserting individual pages into special locations, the Acrobat user interface can be very cumbersome when this is a frequent task. Fortunately, page insertion is also one of the easiest tasks to automate and has been part of the Acrobat JavaScript model since version 5.

About page insertion

Page insertion is performed with the doc.insertPages() function. This function takes four input arguments: the page number where insertion starts, a path to the PDF that is the source of the insertion pages, and the start and ending pages to insert from the source PDF. To start, we need two PDF files for an insertion example, a source document and a destination document. You can create your own, or download the following two files to a single folder on your hard drive.

InsertExampleSource.pdf
InsertExampleDest.pdf

If you create your own sample files, make sure each has four easily identifiable pages. Also, make sure both files are in the same folder.

Open “InsertExampleDest.pdf” in Acrobat Professional. The JavaScript insertion function always acts on the currently open PDF.

Inserting a page into a PDF is a major document modification, so it is not an operation that can be done in Adobe Reader, and it requires a Privileged Context. At its simplest, a Privileged Context means this operation cannot be done from a Document Level script, i.e., documents can’t insert pages into themselves. This has to be done from an Application Level script.

For this example we’ll be running our code from the JavaScript Console window. The JavaScript Console gives our code privilege, so it’s handy for running cut-and-paste automation code like the insertion function, but it is also the essential tool for Acrobat JavaScript development and should be used for all code development. If the console is not enabled, or you have not used it before, then please read the JavaScript Console article.

After opening InsertExampleDest.pdf, display the JavaScript Console from the Advanced > Document Processing menu item or by pressing Ctrl + j. Enter the following code into the console window:

this.insertPages({cPath:"InsertExampleSource.pdf"});

At a minimum, only the path argument, cPath, has to be specified; and since both files are in the same folder, we only need to specify the name of the source file, not the full path. Notice the object notation being used to pass the arguments into the function. This is an Acrobat DOM feature, not a core JavaScript feature. It only works on functions that are part of the Acrobat JavaScript Model. It’s useful because it saves us from having to specify the other optional arguments.

Before running this code, open up the Pages panel (Figure 1). Run the code by placing the cursor on the same line as the code in the JavaScript Console and pressing Ctrl+Enter. The source PDF has a blue-ish background so it is easy to see that all pages from the source PDF are inserted after the first page (Figure 2). Because the page number of the insertion point was not included, the insertPages() function uses the default value, which is the first page in the document. Page numbers used in Acrobat JavaScript always start at 0, so the first page in the PDF is page number 0.

To insert pages into a specific location, the page after which pages are to be inserted is specified. This is the nPage argument. Before running any of the following code from the JavaScript Console, first revert the open PDF to its unchanged state by selecting Revert from the File menu. Also, note that a few of the following examples have multiple lines. To run these from the JavaScript Console, select all the lines before pressing Ctrl + Enter.

To append the entire source PDF to the end of the currently open PDF, use this code:

this.insertPages({nPage:this.numPages-1, cPath:"InsertExampleSource.pdf"});

To insert the entire source PDF in front of the pages in the open PDF, use the code below. Notice that “-1” is used as the insertion point.

this.insertPages({nPage:-1, cPath:"InsertExampleSource.pdf"});

To insert the entire source PDF after page two, use the following code. Notice the code does not use the object notation. The first argument is the insertion point and the second argument is the source file path, so the object notation is unnecessary.

this.insertPages( 1, "InsertExampleSource.pdf");

To insert a single page from the source file, we need another argument, the starting page in the source PDF. In the code below, page three from the source PDF is inserted after page two in the open PDF.

this.insertPages({nPage:1, cPath:"InsertExampleSource.pdf", nStart:2 });

To insert a range of pages from the source file, we need yet another argument, the ending page number. In this example, pages three and four of the source PDF are inserted after page one of the currently open PDF.

this.insertPages({nPage:0, cPath:"InsertExampleSource.pdf", nStart:2, nEnd:3 });

Using the example scripts

As stated earlier, the insertPages() function does not work in Adobe Reader and requires a Privileged Context. It, and other functions like it--such as replacePages(), deletePages(), movePage(), and addWaterMarkFromFile() — are all used to automate document-preparation tasks. As such, they are not intended for use in document scripts.

In the examples above, we ran the code by copying and pasting the scripts from this article into the JavaScript Console window. In fact, for doing simple automation tasks, it’s a good idea to place all your favorite scripts into a text document from which you can copy and paste.

To insert pages into a group of files, you would use a Batch Sequence. Batch Sequences are a Privileged Context, so any of the example code could be copied directly into a Batch Sequence.

A more interesting and useful way to run an automation script is with an Acrobat Toolbar Button or Menu Item. However, using one of these options requires that the code be enclosed in a trusted function. Code for creating toolbar buttons and trusted functions can be found in this article, Applying PDF security with Acrobat JavaScript.

For more information on functions used in this article, see the Acrobat JavaScript Reference and the Acrobat JavaScript Guide.

http://www.adobe.com/devnet/acrobat/

Click on the Documentation tab and scroll down to the JavaScript section.