Skip to main content

Instructions Using Client Libraries


The DynamicPDF Cloud API's client libraries make creating an instructions document easier when you use one of the client libraries. On this page we illustrate using the API rather than JSON to create an instructions document.


The final truth on how to create an instructions document should always be the schema (https://www.dynamicpdf.com/schemas/DLEX20.xsd). However, the DynamicPDF Cloud API also provides several client libraries to make creating instructions for the pdf endpoint easier. Each library has its respected object model to support creating an instructions document for the pdf endpoint.

info

This page discusses the instructions document portion of the client libraries. Refer to the Users Guide Overview, or the readme on each client library's GitHub page for more details on using the client library with the DynamicPDF Cloud API's endpoints.

This Users Guide page discusses using the pdf endpoint with the endpoint's associated instructions document. Refer to the Users Guide page on the other DynamicPDF Cloud API endpoints for more information on using the other endpoints such as dlex-layout or pdf-text.

pdf Endpoint#

Recall that the pdf endpoint uses a JSON instructions document to create the processing instructions for this endpoint. The instructions document allows creating a PDF from scratch, converting images to PDF, processing a dlex document, and then merging the results of the various tasks into a combined PDF.

Refer to the pdf endpoint for instructions on using the endpoint. Here, discussion is limited to creating instructions for the pdf endpoint to process.

Examples Using pdf Endpoint#

All code snippets presented here are also available as complete working examples on DynamicPDF's GitHub site. To find the relevant example code, look for a top-level class named InstructionsExample to find the relevant code. For convenience, the following lists each example's GitHub project.

API Sample ProjectsNamespace/ClassGitHub Location
C#UsersGuidePdfInstructions namespacehttps://github.com/dynamicpdf-api/dotnet-client-examples
JavaUsersGuidePdfInstructions.javahttps://github.com/dynamicpdf-api/java-client-examples
Node.jsUsersGuidePdfInstructions.jshttps://github.com/dynamicpdf-api/nodejs-client-examples
PHPUsersGuidePdfInstructions.phphttps://github.com/dynamicpdf-api/php-client-examples
info

Each code example listed below is a method in the UsersGuidePdfInstructions class.

Although you can construct the instructions document as a JSON document which you then pass to the pdf endpoint, the DynamicPDF Cloud API also provides several client libraries you can use to create an instructions document. In the remainder of this Users Guide page, each section illustrates creating instructions documents performing various tasks. It lists the client library code and and also lists the resultant JSON instructions document.

Top Level Instructions#

An instructions document's top-level elements describe a PDF's metadata. You can specify a PDF's author, title, keywords, fonts, and other data pertinant to the PDF as a whole.

JSON#

The following JSON code snippet illustrates using top-level instructions in an instructions JSON document.

{  "fonts":[    {      "name":"courier"    }  ],  "author":"John Doe",  "title":"Sample PDF",  "subject":"topLevel document metadata",  "creator":"John Creator",  "keywords":"dynamicpdf api example pdf java instructions",  "flattenAllFormFields":false,  "retainSignatureFormFields":false,  "inputs":[    {      "pageWidth":1008.0,      "pageHeight":612.0,      "type":"page"    },    {      "pageWidth":1008.0,      "pageHeight":612.0,      "elements":[        {          "placement":"topRight",          "fontSize":24.0,          "text":"1",          "type":"pageNumbering",          "font":"courier",          "color":"Red"        }      ],      "type":"page"    }  ]}

Client APIs#

If you choose to use one of DynamicPDF's client-libraries, then you can create the instructions document programmatically. The following code snippet illustrate adding top-level metadata to a simple blank PDF. For all languages, the steps are the same.

  • Create a new pdf instance.
  • Add a PageInput instance to the pdf instance by using the AddPage method. Here, we don't do anything with the created PageInput and so we do not get a reference to the instance.
  • Add the top-level metadata to the Pdf instance.

Figure 1. Metadata added to resulting PDF.

Fonts#

The fonts array in the instructions schema allows adding one or more fonts to your instructions document; the following example illustrates adding a font to a newly created PDF. The example also demonstrates how to add a resource from your local system and a resource in your samples/shared folder in the DynamicPDF Cloud API Resource Manager.

JSON#

{  "fonts":[    {      "name":"helvetica"    },    {      "name":"559985a7-e574-4d10-9efd-97a6751c584c",      "resourceName":"samples/shared/font/Calibri.otf"    },    {      "name":"6b3eaf86-adc3-43a0-b6eb-0f9b81cf8afa",      "resourceName":"b39256c9-f50c-49ea-85e5-3608798c8633.ttf"    }  ],  "author":"CeteSoftware",  "creator":"DynmaicPDF Cloud Api",  "flattenAllFormFields":false,  "retainSignatureFormFields":false,  "inputs":[    {      "pageWidth":1008.0,      "pageHeight":612.0,      "elements":[        {          "placement":"topRight",          "fontSize":42.0,          "text":"A",          "type":"pageNumbering",          "font":"helvetica",          "color":"Red"        },        {          "placement":"topLeft",          "fontSize":32.0,          "text":"B",          "type":"pageNumbering",          "font":"559985a7-e574-4d10-9efd-97a6751c584c",          "color":"DarkOrange"        },        {          "placement":"topCenter",          "fontSize":42.0,          "text":"C",          "type":"pageNumbering",          "font":"6b3eaf86-adc3-43a0-b6eb-0f9b81cf8afa",          "color":"Green"        }      ],      "type":"page"    }  ]}

Client APIs#

The following example illustrates adding fonts to a PDF. The processing steps below are the same for all four languages.

  • Create a new Pdf instance and add a new page and get a reference to the created PdfInput instance.
  • Create a PageNumberingElement instance to add the text, "A", to the top-right.
  • Create a second PageNumberingElement instance and add the text, "B", to the top-left.
  • Then create a new Font instance and pass the path to the font from the Resource Manager.
  • Add the font to the second PageNumberingElement instance.
  • Repeat for a third PageNumberingElement instance, only use a local system font.
  • Add the three PageNumberingElement instances to the PageInput instance's Elements collection.

Figure 2. Resultant PDF with added fonts.

Security#

The security schema element is useful for adding security to a generated PDF. The following example illustrates adding a username and password to a PDF.

JSON#

{  "author":"CeteSoftware",  "creator":"DynamicPDF Cloud Api",  "security":{    "userPassword":"myuser",    "ownerPassword":"mypassword",    "allowCopy":false,    "allowEdit":true,    "allowPrint":false,    "allowUpdateAnnotsAndFields":true,    "allowAccessibility":true,    "allowFormFilling":false,    "allowHighResolutionPrinting":true,    "allowDocumentAssembly":false,    "type":"aes256"  },  "flattenAllFormFields":false,  "retainSignatureFormFields":false,  "inputs":[    {      "resourceName":"95154d87-d423-4061-b678-b8a6d01e8eac.pdf",      "type":"pdf"    }  ]}

Client APIs#

The following example illustrates adding security to a PDF. The processing steps below are the same for all four languages.

  • Create a new Pdf instance and add DocumentA.pdf from local system as a PdfResource instance.
  • Add the PdfResource instance to the Pdf instance.
  • Create a new Aes256Security instance and set its username and password in the constructor.

Figure 3. Resultant PDF with added password protection.

Inputs#

All instructions documents must have an inputs array containing one or more input elements. As discussed in the schema section (cloud-api-schema-pdf) of the Users Guide, the valid input types are page, pdf, image, and dlex.

page#

Use a page element to create a single PDF page where you can add additional content using elements from the elements element. Note that what is returned is a PageInput instance. After obtaining a reference to the PageInput instance you can perform further processing tasks on the class.

tip

If creating a complex PDF, consider using Designer to create a DLEX rather than trying to build a PDF using code.

In the code snippet below, we create a new page with the page dimensions, 1008x612.

pdf#

Use a Pdf element to add a PDF to your instructions set. For all client library languages you perform the following steps to add a PDF to a Pdf instance. If the PDF you wish to add resides on the cloud in the Resource Manager, then you add the PDF directly to the parent Pdf instance. If you add the PDF from your local system, then you first create a PdfResource instance and add the instance to the Pdf instance.

image#

The image input type instructs the finished PDF to convert the image to a PDF and then merge it with any other inputs. Each added image is its own PDF page.

dlex#

The dlex type adds a DLEX file to the instructions and processes the file to create a PDF.

Inputs - Merging#

There is no input type for merging as the instruction to merge one or more documents is implicit by including more than one input element. The following examples illustrate how to merge one or more inputs into a new PDF. The example also illustrates adding merge options to a PDF, where the same PDF is merged but the first instance removes the PDF's annotations.

info

When using the pdf endpoint to create processing instructions, you combine one or more elements in the inputs array to merge each input's results into a merged PDF. Refer to the Users Guide schema page for more information on merging (instructions schema).

Inputs are merged in the order in which they are received in the instructions JSON.

JSON#

{  "author": "CeteSoftware",  "creator": "DynamicPDF Cloud Api",  "inputs": [    {      "type": "pdf",      "resourceName": "DocumentA.pdf",    },    {      "type": "image",      "align": "center",      "vAlign": "center",      "resourceName": "dynamicpdflogo.png",    },    {      "type": "pdf",      "resourceName": "DocumentB.pdf",    }  ]}

Client APIs#

The following illustrates merging a PDF, an image, and then another PDF together to form a combined PDF. As the example illustrates, merging three inputs to form a combined PDF is straightforward. You can combine any input type from the inputs array to form a new PDF.

In the following example, all client API languages have the same processing steps.

  • Create a new Pdf instance.
  • Create a new PdfResource instance, a new ImageResource instance, and a new PdfResource instance that specify the three local files.
  • Add the three resources to the Pdf instance to combine them into a merged PDF.

Figure 4. A PDF, followed by an image, and then followed by another PDF combined to form a merged PDF.

AcroForm Fields#

A PDF can be a form with form fields that the end user completes and then saves as a new completed PDF document. You can complete a PDF form programmatically by using the pdf input type combined with processing instructions for the PDF's embedded form fields. The following example illustrates.

JSON#

{  "inputs": [    {      "type": "pdf",      "resourceName": "simple-form-fill.pdf"    }  ],  "formFields": [    {      "name": "nameField",      "value": "DynamicPDF"    },    {      "name": "descriptionField",      "value": "RealTime Pdf's. Real FAST!"    }  ],  "outlines": []}

Client APIs#

The following example illustrates a simple PDF document with two form fields where the values are entered programmatically and then saved to a new PDF. For all four client API languages, the processing steps are the same.

  • Create a new Pdf instance.
  • Add the PDF from local system to a new PdfResource instance.
  • Add values to the PDF's two form fields as new FormField instances.
  • Add the FormField instances to the new PDF with the completed form field values.

Figure 5. PDF form with form field values entered programmatically.

Outlines#

You add bookmarks/outline to a PDF using the outlines array in the processing instructions. The following two examples illustrate creating a new PDF and adding an outline and then adding an outline to an existing PDF. The first example illustrates a creating an outline from scratch while the second example works with a pre-existing outline.

Creating New Page with Outline#

The following example shows creating a PDF using the page element and adding an outline from scratch.

JSON#

{  "author":"John Doe",  "title":"New Outline Sample Pdf",  "creator":"DynamicPDF Cloud Api",  "flattenAllFormFields":false,  "retainSignatureFormFields":false,  "inputs":[    {      "id":"1f2c5e25-9814-4e42-a934-b45b56748b04",      "elements":[        {          "placement":"topCenter",          "text":"Hello World 1",          "type":"text"        }      ],      "type":"page"    },    {      "id":"4d1227c1-598e-456f-a67d-0b6f3c7b607f",      "elements":[        {          "placement":"topCenter",          "text":"Hello World 2",          "type":"text"        }      ],      "type":"page"    },    {      "id":"a8c0d4ff-2a1f-48e6-95d0-2170354e7477",      "elements":[        {          "placement":"topCenter",          "text":"Hello World 3",          "type":"text"        }      ],      "type":"page"    }  ],  "outlines":[    {      "text":"Root Outline",      "expanded":false,      "children":[        {          "text":"Page 1",          "expanded":false,          "linkTo":{            "pageOffset":0,            "pageZoom":"fitPage",            "inputID":"1f2c5e25-9814-4e42-a934-b45b56748b04"          }        },        {          "text":"Page 2",          "expanded":false,          "linkTo":{            "pageOffset":0,            "pageZoom":"fitPage",            "inputID":"4d1227c1-598e-456f-a67d-0b6f3c7b607f"          }        },        {          "text":"Page 3",          "expanded":false,          "linkTo":{            "pageOffset":0,            "pageZoom":"fitPage",            "inputID":"a8c0d4ff-2a1f-48e6-95d0-2170354e7477"          }        }      ]    }  ]}

Client APIs#

The processing steps are the same for all four client API language.

  • Create a new Pdf instance.
  • Create a new TextElement instance and add it to the first page.
  • Create a second page and add text to the page.
  • Add a third page and add text to the page.

Now that we have three new PDFs to be merged (the three new pages) let's create the outline.

  • Create a new Outline instance and create the top-level outline bookmark (the root element).
  • Get a reference to the Outline instance's Children collection and add three more bookmarks. Note that each bookmark refers to the newly created page (PDF to merge).

The finished PDF contains an outline consisting of the root outline, followed by the three new bookmarks. Each bookmark links to the newly created PDF that was merged to the final PDF.

Figure 6. PDF with added outline.

Add Outline to Existing PDF#

The following example illustrates merging existing PDFs and adding an outline.

JSON#

{  "author":"John Doe",  "title":"Existing Pdf Example",  "creator":"DynmaicPDF Cloud Api",  "flattenAllFormFields":false,  "retainSignatureFormFields":false,  "inputs":[    {      "resourceName":"7c131f14-3148-47c9-b28b-349f4562b004.pdf",      "id":"AllPageElements",      "mergeOptions":{        "outlines":false      },      "type":"pdf"    },    {      "resourceName":"7c131f14-3148-47c9-b28b-349f4562b004.pdf",      "id":"AllPageElements",      "mergeOptions":{        "outlines":false      },      "type":"pdf"    },    {      "resourceName":"3a161f25-db1b-449b-a7af-7dfdb6ad152d.pdf",      "id":"outlineDoc1",      "mergeOptions":{        "outlines":false      },      "type":"pdf"    },    {      "resourceName":"3a161f25-db1b-449b-a7af-7dfdb6ad152d.pdf",      "id":"outlineDoc1",      "mergeOptions":{        "outlines":false      },      "type":"pdf"    }  ],  "outlines":[    {      "text":"Imported Outline",      "expanded":true,      "children":[        {          "expanded":false,          "fromInputID":"AllPageElements"        },        {          "expanded":false,          "fromInputID":"outlineDoc1"        }      ]    }  ]}

Client APIs#

Figure 7. Resultant PDF with an existing outline.

Templates#

Use the templates array to add one or more templates to a resulting PDF document. The following example illustrates a simple template created by adding text that is centered at the top of a PDF.

Json#

{  "templates": [    {      "id": "Temp1",      "elements": [        {          "type": "text",          "text": "Hello World",          "placement": "topCenter",          "xOffset": 0.0,          "yOffset": 0.0        }      ]    }  ],  "inputs": [    {      "type": "pdf",      "templateId": "Temp1",      "resourceName": "DocumentA.pdf"    }  ],  "formFields": []}

Client APIs#

Figure 8. PDF with an added template.

Barcode#

You can add a barcode to a PDF by adding a barcode element to a template. Supported barcodes include linear, two-dimensional, and postal barcodes.

Linear Barcodes#

  • Codabar
  • Code 128
  • Code 2 of 5
  • Code 3 of 9 & extended 3 of 9
  • Code 11
  • Code 93 & extended 93
  • EAN/JAN 13
  • EAN/JAN 13 Supplement 2
  • EAN/JAN 13 Supplement 5
  • EAN 14/GTIN-14
  • EAN/JAN 8
  • EAN/JAN 8 Supplement 2
  • EAN/JAN 8 Supplement 5
  • GS1 Databar (RSS)
  • IATA 2 of 5
  • Interleaved 2 of 5
  • ISBN
  • ISBN Supplement 2
  • ISBN Supplement 5
  • ISMN
  • ISMN Supplement 2
  • ISMN Supplement 5
  • ISSN
  • ISSN Supplement 2
  • ISSN Supplement 5
  • ITF 14
  • MSI Barcode (Modified Plessey)
  • Stacked GS1 Databar
  • UPC Version A
  • UPC Version A Supplement 2
  • UPC Version A Supplement 5
  • UPC Version E
  • UPC Version E Supplement 2
  • UPC Version E Supplement 5

Two-Dimensional Barcodes#

  • Aztec
  • Data Matrix Barcode
  • MacroPDF417
  • PDF417
  • QR Code

Postal Barcodes#

  • Australia Post
  • Deutsche Post Identcode
  • Deutsche Post Leitcode
  • Intelligent Mail Barcode
  • KIX (Dutch KIX, Royal TNT Post Kix)
  • Postnet
  • RM4SCC (Royal Mail) Barcode
  • Singapore Post

JSON#

{  "templates": [    {      "id": "Temp1",      "elements": [        {          "type": "aztecBarcode",          "valueType": "string",          "value": "Hello World",          "placement": "topCenter",          "xOffset": 0.0,          "yOffset": 500.0        }      ]    }  ],  "author": "CeteSoftware",  "creator": "DynamicPDF Cloud Api",  "inputs": [    {      "type": "pdf",      "templateId": "Temp1",      "resourceName": "DocumentA.pdf"    }  ]}

Client APIs#

Figure 9. PDF with an added barcode.