Skip to main content

Instructions Overview

The DynamicPDF API's client libraries make creating an instructions document easier when you use one of the client libraries.

The final truth on how to create an instructions document should always be the schema; however, the DynamicPDF API also provides several client libraries to make creating instructions for the pdf endpoint easier.

info

Refer to Instructions Schema Diagram to review the JSON schema.

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 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 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 or UsersGuidePdfInstructions 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/blob/main/DynamicPdfClientLibraryExamples/Examples/InstructionsExample.cs
JavaInstructionsExamples.javahttps://github.com/dynamicpdf-api/java-client-examples/blob/main/src/main/java/com/dynamicpdf/api/examples/instructions/InstructionsExamples.java
Node.jsInstructionsExample.jshttps://github.com/dynamicpdf-api/nodejs-client-examples/blob/main/InstructionsExample.js
PHPInstructionsExample.phphttps://github.com/dynamicpdf-api/php-client-examples/blob/main/InstructionsExample.php
Gopdf-instructions-example.gohttps://github.com/dynamicpdf-api/go-client-examples/blob/main/pdf-instructions-example.go
PythonInstructionsExample.pyhttps://github.com/dynamicpdf-api/python-client-examples/blob/main/InstructionsExample.py
info

Each code example listed below is a method in the file listed above.

Although you can construct the instructions document as a JSON document which you then pass to the pdf endpoint, the DynamicPDF 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, creator, producer and other data pertinent to the PDF as a whole.

caution

The DynamicPDF API free pricing tier ignores the producer metadata property. You must upgrade to one of the paid pricing tiers for your PDFs to display this property (see: Pricing).

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 illustrates 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.
public static Pdf TopLevelMetaData() {
    Pdf pdf = new Pdf();
    pdf.AddPage(1008, 612);
    pdf.Author = "John Doe";
    pdf.Keywords ="dynamicpdf api example pdf java instructions";
    pdf.Creator = "John Creator";
    pdf.Subject = "topLevel document metadata";
    pdf.Title = "Sample PDF";
    return pdf;
}
Source: InstructionsExample.cs

Figure 1. Metadata added to resulting PDF.

tip

Remember, refer to the relevant GitHub project - referenced above - for a complete example.

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 API File Manager.

info

DynamicPDF API also supports Google Fonts.

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"
    }
  ]
}
info

If using the html endpoint, use css to format html. The following code demonstrates.

pdf.AddHtml("<p style='color:red;font-family:verdana;font-size:30px'>Hello DynamicPDF API</html>");

Client APIs​

The Client API's represent Fonts with the Fonts class and supports built-in fonts, fonts loaded from a file, or Google fonts.

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 File 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.
public static Pdf FontsExample(String basePath)
{
    Pdf pdf = new Pdf();
    PageInput pageInput = pdf.AddPage(1008, 612);
    PageNumberingElement pageNumberingElement = new PageNumberingElement("A", ElementPlacement.TopRight);
    pageNumberingElement.Color = RgbColor.Red;
    pageNumberingElement.Font = Font.Helvetica;
    pageNumberingElement.FontSize = 42;
    String cloudResourceName = "samples/fonts-example/Calibri.otf";
    PageNumberingElement pageNumberingElementTwo = new PageNumberingElement("B", ElementPlacement.TopLeft);
    pageNumberingElementTwo.Color = RgbColor.DarkOrange;
    pageNumberingElementTwo.Font = new Font(cloudResourceName);
    pageNumberingElementTwo.FontSize = 32;

    String filePathFont = basePath + "cnr.otf";
    PageNumberingElement pageNumberingElementThree = new PageNumberingElement("C", ElementPlacement.TopCenter);
    pageNumberingElementThree.Color = RgbColor.Green;
    pageNumberingElementThree.Font = Font.FromFile(filePathFont);
    pageNumberingElementThree.FontSize = 42;
    pageInput.Elements.Add(pageNumberingElement);
    pageInput.Elements.Add(pageNumberingElementTwo);
    pageInput.Elements.Add(pageNumberingElementThree);
    return pdf;
}
Source: InstructionsExample.cs
info

See the GoogleFontsExample in the dotnet-client-examples GitHub project for an example using Google Fonts.

PageNumberingElement pageNumberingElementTwo = new PageNumberingElement("Test", ElementPlacement.TopLeft);
pageNumberingElementTwo.Color = RgbColor.DarkOrange;
pageNumberingElementTwo.Font =  Font.Google("Borel", false, false);
pageNumberingElementTwo.FontSize = 42;
Source: InstructionsExample.cs

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.

info

Refer to the documentation outlining security in the JSON schema (JSON Instructions Schema - Security).

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.
public static Pdf SecurityExample(String basePath) {
    Pdf pdf = new Pdf();
    PdfResource pdfResource = new PdfResource(basePath + "DocumentA.pdf");
    pdf.AddPdf(pdfResource);
    Aes256Security sec = new Aes256Security("myuser", "mypassword");
    sec.AllowCopy = false;
    sec.AllowPrint = false;
    pdf.Security = sec;
    return pdf;
}
Source: InstructionsExample.cs

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, html, word, excel and dlex.

input Documentation
page
pdf
image
html
dlex
excel
word
tip

Use the input type's Resource sub-class (for example ImageResource, PdfResource, etc.) to obtain resources from your local system as a file, byte array, or stream. Use the relative path to the resource in your DynamicPDF cloud Storage to load the resource from the cloud. Examples are provided throughout this page and also the pdf Inputs page.

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.

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 File 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.

html​

Use a html element to add HTML to your instructions set. For all client library languages you perform the following steps to add an HTML document or string to a Pdf instance. The html input only accepts HTML as string data; you cannot specify a URL or file path.

DynamicPDF API fully supports HTML 5 and CSS but does not support JavaScript. A basePath must be a public resource available via HTTP.

info

Refer to the HTML Input type documentation and the using the HTML input type with the API client libraries(HtmlInput) for more information.

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. The DynamicPDF API supports the following nine common image types.

File TypeDescription
JPEGJPEGs are handled natively through a highly efficient pass through process.
PNGPNGs are handled natively. If the PNG does not have an alpha channel (transparency), it uses a highly efficient pass through process. If the PNG does have an alpha channel it is parsed and reformatted for inclusion in a PDF document.
BMPBMPs are converted to a bitmap for inclusion in a PDF document.
EMFEMFs are converted to a bitmap for inclusion in a PDF document.
WMFWMFs are converted to a bitmap for inclusion in a PDF document.
EXIFEXIFs are handled natively through a highly efficient pass through process.
JPEG 2000JPEG 2000s are handled natively through a highly efficient pass through process.
GIFGIFs are handled natively, but are parsed and reformatted for inclusion in a PDF document.
TIFFTIFFs are handled natively and most types of TIFFs (LZW being the exception) use a highly efficient pass through process. Multi-page Tiffs are supported, allowing access to any page in a TIFF document.

word​

The word input type instructs the finished PDF to convert the Word document to a PDF and then merge it with any other inputs.

info

See Word in Json Instructions Schema for more information on the word input type and see Inputs - Word topic for code examples.

excel​

The excel input type instructs the finished PDF to convert the Excel document to a PDF and then merge it with any other inputs.

info

See Excel in Json Instructions Schema for more information on the excel input type and see Inputs - Excel topic for code examples.

dlex​

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

PageInput - Elements​

A pageInput is for creating a new single-page PDF. A pageInput supports the following element types.

  • pageNumbering
  • text
  • image
  • line
  • rectangle
  • and barcodes.

The template elements topic below has details on the properties of each of the element types.

info

Refer to the Add Text, Images, Lines, and Rectangles to PDFs solution for an example adding several elements to a page.

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.
public static Pdf MergeExample(String basePath) {
    Pdf pdf = new Pdf();
    PdfResource resourceA = new PdfResource(basePath + "DocumentA.pdf");
    ImageResource imageResource = new ImageResource(basePath + "dynamicpdfLogo.png");
    PdfResource resourceB = new PdfResource(basePath + "DocumentB.pdf");
    pdf.AddPdf(resourceA);
    pdf.AddImage(imageResource);
    pdf.AddPdf(resourceB);
    return pdf;
}
Source: InstructionsExample.cs

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

Form 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.

info

You can also flatten the form fields in a PDF, remove form fields, and retain signature fields. Refer to the following documentation topic on the instructions schema for more information on forms (pdf instructions - 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.
public static Pdf FormFieldsExample(String basePath) {
    Pdf pdf = new Pdf();
    pdf.AddPdf(new PdfResource(basePath + "simple-form-fill.pdf"));
    FormField formField = new FormField("nameField", "DynamicPdf");
    FormField formField2 = new FormField("descriptionField", "RealTime Pdf's. Real FAST!");
    pdf.FormFields.Add(formField);
    pdf.FormFields.Add(formField2);
    return pdf;
}
Source: InstructionsExample.cs

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.

info

Refer to the Outlines topic on JSON Instructions Schema documentation page for the properties associated with the outlines array.

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 Text element 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).
public static Pdf AddOutlinesForNewPdf() {
    Pdf pdf = new Pdf();
    PageInput pageInput = pdf.AddPage();
    TextElement element = new TextElement("Hello World 1", ElementPlacement.TopCenter);
    pageInput.Elements.Add(element);
    PageInput pageInput1 = pdf.AddPage();
    TextElement element1 = new TextElement("Hello World 2", ElementPlacement.TopCenter);
    pageInput1.Elements.Add(element1);
    PageInput pageInput2 = pdf.AddPage();
    TextElement element2 = new TextElement("Hello World 3", ElementPlacement.TopCenter);
    pageInput2.Elements.Add(element2);
    Outline rootOutline = pdf.Outlines.Add("Root Outline");
    rootOutline.Children.Add("Page 1", pageInput);
    rootOutline.Children.Add("Page 2", pageInput1);
    rootOutline.Children.Add("Page 3", pageInput2);
    return pdf;
}
Source: InstructionsExample.cs

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​

public static Pdf AddOutlinesExistingPdf(String basePath) {

    Pdf pdf = new Pdf();
    PdfResource resource = new PdfResource(basePath + "AllPageElements.pdf");
    PdfInput input = pdf.AddPdf(resource);
    input.Id = "AllPageElements";
    pdf.Inputs.Add(input);

    PdfResource resource1 = new PdfResource(basePath + "OutlineExisting.pdf");
    PdfInput input1 = pdf.AddPdf(resource1);
    input1.Id = "outlineDoc1";
    pdf.Inputs.Add(input1);

    Outline rootOutline = pdf.Outlines.Add("Imported Outline");
    rootOutline.Expanded = true;
    rootOutline.Children.AddPdfOutlines(input);
    rootOutline.Children.AddPdfOutlines(input1);
    return pdf;
}
Source: InstructionsExample.cs

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​

public static Pdf TemplateExample(String basePath) {
    Pdf pdf = new Pdf();
    PdfResource resource = new PdfResource(basePath + "/DocumentA.pdf");
    PdfInput input = new PdfInput(resource);
    pdf.Inputs.Add(input);
    
    Template template = new Template("Temp1");
    TextElement element = new TextElement("Hello World", ElementPlacement.TopCenter);
    template.Elements.Add(element);
    input.Template = template;
    return pdf;
}
Source: InstructionsExample.cs

Figure 8. PDF with an added template.

Template Elements​

Add one or more elements when creating a template. The Following elements are supported.

  • PageNumbering
  • Text
  • Image
  • Rectangle
  • Line
  • Barcode
info

Refer to the Add Text, Images, Lines, and Rectangles to Existing PDFs solution for an example adding several elements to a template.

The following properties are shared by all elements.

PropertyType
typepageNumbering, text, image, rectangle, line(see barcodes for barcode types)
placementtopLeft, topCenter, topRight, bottomLeft, bottomCenter, bottomRightREQUIRED
xOffsetnumber
yOffsetnumber
color(see colors)
font(see fonts)
fontSizenumber
textstringREQUIRED
evenPagesboolean
oddPagesboolean

Page Numbering​

The pageNumbering element type adds numbers to pages. Use the following tokens within the text of a pageNumbering element and the tokens are replaced with the appropriate value when the PDF is created. Surround elements with the %% character.

TOKENEXAMPLEDESCRIPTION
CP%%CP%%Current page. The default numbering style is numeric. The current page can be offset using the is offset by the page property.
TP%%TP%%Total pages. The default numbering style is numeric. The total pages can be offset using the is offset by the pageTotalOffset property.

Image​

PropertyType
resourceNamestringREQUIREDThe resource file name or path of the image. Resides in cloud environment or uploaded as resource.
maxWidthnumber
maxHeightnumber
scaleXnumber
scaleYnumber

Text​

The text element type adds text to a template.

Rectangle​

The rectangle element adds a rectangle to a template.

PropertyType
widthnumberREQUIRED
heightnumberREQUIRED
cornerRadiusnumber
borderWidthnumber
borderStyledash, dashLarge, dashSmall, dots, solid
borderColor(see colors)
fillColor(see colors)

Line​

The line element type adds a line to a template.

PropertyType
y2OffsetnumberREQUIRED
x2OffsetnumberREQUIRED
lineStyledash, dashLarge, dashSmall, dots, solid

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.

info

You can also add barcodes to a PDF using our graphical editor, the DynamicPDF Designer.

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​

public static Pdf BarcodeExample(String basePath) {
    Pdf pdf = new Pdf();
    PdfResource resource = new PdfResource(basePath + "/DocumentA.pdf");
    PdfInput input = new PdfInput(resource);
    pdf.Inputs.Add(input);

    Template template = new Template("Temp1");
    AztecBarcodeElement element = new AztecBarcodeElement("Hello Barcode", ElementPlacement.TopCenter, 0, 500);
    template.Elements.Add(element);
    input.Template = template;
    return pdf;
}
Source: InstructionsExample.cs

Figure 9. PDF with an added barcode.

info

The DynamicPdf API allows creating complex instructions documents, and there are many subtle nuances in each of the client libraries. For questions, be certain to contact us at support@dynamicpdf.com. But if you do, please be certain to provide relevant source code of what you are trying to accomplish.