Skip to main content

Adding Bookmarks to a PDF

Use the Outline element in JSON instructions with the pdf endpoint to create a PDF that includes bookmarks for a combined PDF.

In this tutorial you merge three PDF documents and combine the three PDFs and add bookmarks to the merged PDF document. You also create a bookmark with an external URL and add it to the PDF's outline.

Required Resources​

To complete this tutorial, add the Adding Bookmarks sample to your samples folder in your cloud storage space using the File Manager. After adding the sample resources, you should see the samples/adding-bookmarks-pdf-endpoint folder containing the resources used in this tutorial.

SampleSample FolderResources
Adding Bookmarkssamples/adding-bookmarks-pdf-endpointDocumentA.pdf, DocumentB.pdf, DocumentC.pdf, and instructions.json

  • From the File Manager, download the three PDF documents and instructions.json to your local system; here we assume /temp/dynamicpdf-api-samples/add-bookmarks.

  • After downloading, delete the three PDFs and instructions.json from your cloud storage space using the File Manager. We delete these resources so that we can use the resources from the previous tutorial.

info

If you do not plan on duplicating this tutorial's steps, then do not delete the resources.

ResourceCloud/Local
DocumentA.pdflocal
DocumentB.pdflocal
DocumentC.pdflocal
instructions.jsonlocal
tip

See Sample Resources for instructions on adding sample resources.

Obtaining API Key​

This tutorial assumes a valid API key obtained from the DynamicPDF API's Portal. Refer to the following for instructions on getting an API key.

tip

If you are not familiar with the File Manager or Apps and API Keys, refer to the following tutorial and relevant Users Guide pages.*

Calling API Directly Using POST​

Merging three pre-existing PDFs and saving them as a new PDF requires using the pdf endpoint. The pdf endpoint uses an instructions JSON document you send to the endpoint. The endpoint then processes the instructions to create the resultant PDF. When you call the pdf endpoint directly, you must create an instructions document. When you use one of the DynamicPDF client libraries, the client library hides the complexities of creating the instructions document from you.

Now let's create the JSON instructions document.

Create JSON Instructions​

  • Open a text editor and create the following instructions JSON document and name it instructions.json.
  • Add the three inputs of type pdf.
  • Assign each input an id.
  • Add the bookmarks to the instructions.
  • Note that each outline element refers to the id of its related document.
  • Save instructions.json to /temp/dynamicpdf-api-samples/add-bookmarks.
{
  "inputs": [
    {
      "type": "pdf",
      "resourceName": "DocumentA.pdf",
      "id": "documentA"
    },
    {
      "type": "pdf",
      "resourceName": "DocumentB.pdf",
      "id": "documentB"
    },
    {
      "type": "pdf",
      "resourceName": "DocumentC.pdf",
      "id": "documentC"
    }
  ],
  "outlines": [
    {
      "color": "Red",
      "text": "Three Bookmarks",
      "style": "boldItalic",
      "expanded": true,
      "children": [
        {
          "color": "Orange",
          "text": "DocumentA",
          "linkTo": {
            "inputID": "documentA"
          }
        },
        {
          "color": "Green",
          "text": "DocumentB",
          "linkTo": {
            "inputID": "documentB",
            "pageOffset": 2
          }
        },
        {
          "color": "Purple",
          "text": "DocumentC",
          "linkTo": {
            "inputID": "documentC"
          }
        },
        {
          "color": "Blue",
          "text": "DynamicPDF API",
          "linkTo": {
            "url": "https://dpdf.io/"
          }
        }
      ]
    }
  ]
}

The inputs array refers to the inputs to the created PDF. The outlines array lists any outlines added to the PDF. Note that each input has an id corresponding to the inputID value in the outline element. The inputID ties the outline to the resource. Finally, the fourth outline element is a link to an external URL.

We can now use the cURL command to call the pdf endpoint.

cURL Command​

Before calling the cURL command, ensure you have the following resources in your local filesystem.

/temp/dynamicpdf-api-samples/add-bookmarks
instructions.json
DocumentA.pdf
DocumentB.pdf
DocumentC.pdf
  • Create the following cURL command and call the pdf endpoint.
curl https://api.dpdf.io/v1.0/pdf 
-H "Authorization:Bearer DP.xxx-api-key-xxx" 
-F "Instructions=@C:/temp/dynamicpdf-api-samples/add-bookmarks/instructions.json" 
-F "Resource=@C:/temp/dynamicpdf-api-samples/add-bookmarks/DocumentA.pdf" 
-F "Resource=@C:/temp/dynamicpdf-api-samples/add-bookmarks/DocumentB.pdf" 
-F "Resource=@C:/temp/dynamicpdf-api-samples/add-bookmarks/DocumentC.pdf" 
-o add-bookmarks-output.pdf

In the preceding cURL command, the -H parameter specifies that a header variable named Authorization is sent to the endpoint.

info

The video for this tutorial uses Postman to call the pdf endpoint.

The first -F parameter specifies that it is a form field with the name of Instructions and the path to the instructions document as the value. The second, third, and fourth -F parameters specify Resource as the form field and then the path to the local file as the value.

tip

If a filename in the cURL command does not match the filename in the instructions document, then add the filename by using a semicolon followed by the filename from the instructions document.

"Resource=@C:/temp/dynamicpdf-api-samples/DocumentB.pdf;MyDocument"

The -o parameter specifies the output file to write the response to.

info

Note that we are assuming the cURL command is executed in the same folder as where we stored our resources. If calling cURL from somewhere other than the folder containing your resources, then you must also specify the path to the outputted document.

  • Execute the curl command and generate the PDF document.
  • Open the created PDF, add-bookmarks-output.pdf to view the merged PDF with the added bookmarks.

Figure 1. The PDF has three bookmarks and a link to an external website.

Calling Endpoint Using Client Library​

Of course, creating an instructions document by hand can be tedious and error-prone. To simplify your development, you can instead use one of the DynamicPDF API client libraries.

Let's use the client libraries to generate the PDF rather than the instructions document.

Complete Source​

Use the client library of your choice to complete the next tutorial section. Each client library tab contains tutorial steps particular to the selected language.

Access the complete source for this project at one of the following GitHub projects.

LanguageGitHub Users Guide ProjectExample Class FileLocation/Package/Namespace
C#https://github.com/dynamicpdf-api/dotnet-client-examplesProgram.csnamespace AddBookmarks
Javahttps://github.com/dynamicpdf-api/java-client-examplesAddBookmarks.javacom.dynamicpdf.api.examples
Node.jshttps://github.com/dynamicpdf-api/nodejs-client-examplesAddBookmarks.jsnodejs-client-examples
PHPhttps://github.com/dynamicpdf-api/php-client-examplesAddBookmarks.phpphp-client-examples
GOhttps://github.com/dynamicpdf-api/go-client-examples/tree/mainadd-bookmarks-example.gogo-client-examples
Pythonhttps://github.com/dynamicpdf-api/python-client-examplesAddBookmarks.pypython-client-examples
tip

Click on the language tab of choice to view the tutorial steps for the particular language.

Available on NuGet:

Install-Package DynamicPDF.API
  • Create a new Console App (.NET Core) project named AddBookmarks.
  • Add the DynamicPDF.API NuGet package.
  • Create a new static method named Run.
  • Add the following code to the Run method.
  • Create a new Pdf instance and assign the api key.
  • Create three new PdfResource instances, one for each PDF to be merged.
  • Add the PdfResource to the Pdf instance, but return a reference to each PdfInput instance.
  • Set the Id of each input to the document's name.
  • Create a top-level root outline and make the color red.
  • Add three child outline elements and set each element's color.
  • Create a new URL outline element and assign it a UrlAction.
  • Call the Pdf instance's Process method.
  • If the results is successful, then save the PDF response Content (a byte array) to a file.
using DynamicPDF.Api;
using System;
using System.IO;

namespace AddBookmarks
{
    class Program
    {
        static void Main(string[] args)
        {
            Run("DP.xxx--apikey---xxx", "C:/temp/dynamicpdf-api-samples/add-bookmarks/");
        }

        public static void Run(String apiKey, String basePath)
        {
            Pdf pdf = new Pdf();
            pdf.ApiKey = apiKey;

            //add three PDF documents as PdfInputs

            PdfResource resource = new PdfResource(basePath + "DocumentA.pdf");
            PdfInput inputA = pdf.AddPdf(resource);
            inputA.Id = "documentA";

            PdfResource resourceB = new PdfResource(basePath + "DocumentB.pdf");
            PdfInput inputB = pdf.AddPdf(resourceB);
            inputB.Id = "documentB";

            PdfResource resourceC = new PdfResource(basePath + "DocumentC.pdf");
            PdfInput inputC = pdf.AddPdf(resourceC);
            inputC.Id = "documentC";

            //create a root outline and then add the three documents as children Outline instances

            Outline rootOutline = pdf.Outlines.Add("Three Bookmarks");
            Outline outlineA = rootOutline.Children.Add("DocumentA", inputA);     
            Outline outlineB = rootOutline.Children.Add("DocumentB", inputB, 2);
            rootOutline.Children.Add("DocumentC", inputC).Color = RgbColor.Purple;

            //add some color to the outline elements

            rootOutline.Color = RgbColor.Red;
            rootOutline.Style = OutlineStyle.BoldItalic;
            outlineA.Color = RgbColor.Orange;
            outlineB.Color = RgbColor.Green;

            //add an outline element that links to a URL

            Outline outlineD = rootOutline.Children.Add("DynamicPDF API");
            outlineD.Color = RgbColor.Blue;
            outlineD.Action = new UrlAction("https://dpdf.io/");

            rootOutline.Expanded = true;

            PdfResponse response = pdf.Process();
            
            if(response.IsSuccessful)
            {
                Console.WriteLine(PrettyPrintUtil.JsonPrettify(pdf.GetInstructionsJson()));
                 File.WriteAllBytes(basePath + "add-bookmarks-output.pdf", response.Content);
            } else
            {
                Console.WriteLine(PrettyPrintUtil.JsonPrettify(pdf.GetInstructionsJson()));
                Console.WriteLine(response.ErrorJson);
            }
        }

    }
}

In all six examples, the processing steps were the same. First, we created a new Pdf instance to construct the finished PDF. We then loaded four PDFs into PdfResource instances and added them to the Pdf instance. We used the resulting references to PdfInput to assign IDs for each added PDF.

After adding the PDF documents to merge, we obtained a reference to an Outline instance from the Pdf instance by adding a new outline with text. We then added three more Outline instances as children to the top-level Outline instance. Then we added a final Outline instance that linked to a URL.

The endpoint returned a merged PDF where each outline element is a bookmark to the original PDF that was merged.

Figure 2. The outline created by merging three PDFs and a URL to an external website.

   Follow us on social media for latest news!