Skip to main content

pdf Inputs

The pdf endpoint has six input types dlex, image, html, word, page, and pdf. Use these inputs to create rich PDF documents.

The DynamicPDF API's pdf endpoint uses a JSON document that provides processing instructions for manipulating PDFs. The instructions document has six input types.

endpointdescription
dlexSpecifies a DLEX document used with JSON layoutdata to create a rich PDF document/report.
imageSpecifies an image that is converted into a PDF.
htmlSpecifies an HTML document or fragment that is converted into a PDF.
wordSpecifies a Word document that is converted into a PDF.
excelSpecifies an Excel document that is converted into a PDF.
pageSpecifies one or more inputs to create a new single-page PDF.
pdfSpecifies a pre-existing PDF to be be combined with one or the other input types to create a new PDF. Optionally allows applying templates to an existing PDF to overlay elements such as text, shapes, and images.
info

Refer to documentation on the instructions schema for more general information on how to use the pdf endpoint.

Use the six input types in any combination to combine into a merged PDF document.

tip

For all inputs, input the relative path to the resource as a string if using a resource such as a DLEX file, image, or layout data that resides in your DynamicPDF API's cloud storage. Otherwise, you will use one of the input's associated resource classes if the resource is on your local system.

info

The resources for all the examples in this documentation are available from samples/users-guide-resources in cloud storage. See environment-manager-sample-resources for more information.

DlexInput​

The DlexInput class adds a DLEX file to an instructions document for processing by the pdf endpoint. This input type is used in combination with DynamicPDF Designer to create rich reports/documents.

info

See the Designer documentation for more information on using Designer.

The .NET C# client library DlexInput class has the following constructors.

Constructors​

public DlexInput(DlexResource dlexResource, LayoutDataResource layoutData);
public DlexInput(DlexResource dlexResource, string layoutData);
public DlexInput(string cloudResourcePath, LayoutDataResource layoutData);
public DlexInput(string cloudResourcePath, string layoutData);
Source: DlexInput.cs
  • The DlexResource class obtains the DLEX for processing.
  • The LayoutDataResource class obtains the JSON data processed by the DLEX to create the resultant PDF report.
  • The cloudResourcePath string passes the relative path to a DLEX file in your cloud storage.
  • The layoutData string that passes the path in your local storage to the JSON layout data.
info

You do not create a DlexInput instance directly. Instead, you pass the DlexResource and LayoutDataResource to the Pdf class's AddDlex method.

Properties​

The DlexInput class has one property, which you set via the Pdf AddDlex method rather than through a DlexInput instance.

public string LayoutDataResourceName { get; set; }
Source: DlexInput.cs

LayoutDataResource​

The LayoutDataResource class accepts a serializable object containing JSON data or a string. If an object, then the JSON-compatible object is serialized into JSON using the Newsoft.Json.Serialization class. If a string, then the string is assumed to be a path to a JSON document.

Constructors​
public LayoutDataResource(object layoutData, string layoutDataResourceName = null);
public LayoutDataResource(string layoutData, string layoutDataResourceName = null);
Source: LayoutDataResource.cs
Properties​
public string LayoutDataResourceName { get; set; }
Source: LayoutDataResource.cs

DlexResource​

The DlexResource class accepts a string, byte array, or a Stream. If a string, the constructor assumes a path to a DLEX file. Otherwise, it expects the data as either a byte array or Stream.

Constructors​
public DlexResource(string dlexPath, string resourceName = null) : base(dlexPath, resourceName)
public DlexResource(byte[] value, string resourceName = null)
public DlexResource(Stream data, string resourceName = null) : base(data, resourceName)
Source: DlexResource.cs

Examples​

The following example illustrates using a DLEX file and JSON file that reside on a local filesystem.

Pdf pdf = new Pdf();
DlexResource dlex = new DlexResource("c:/temp/dlex-resource/SimpleReportWithCoverPage.dlex");
LayoutDataResource layout = new LayoutDataResource("c:/temp/dlex-resource/SimpleReportWithCoverPage.json");
pdf.AddDlex(dlex, layout);
return pdf;
Source: InstructionsExample.cs

The DlexResource and LayoutDataResource classes have constructors that allow a byte array or a stream. The data could come from any number of sources, including a database. The following example illustrates.

danger

If you use a DLEX file that resides locally on your system, remember any embedded resources must also reside in a path reachable by the DLEX. 

Pdf pdf = new Pdf();
//get the DLEX from local filesystem
DlexResource dlexResource = new DlexResource("c:/temp/users-guide-resources/SimpleReportWithCoverPage.dlex");
LayoutDataResource layout = new LayoutDataResource("c:/temp/users-guide-resources/SimpleReportWithCoverPage.json");
pdf.AddDlex(dlexResource, layout);
//get the image embedded in the dlex from local filesystem
pdf.AddAdditionalResource("c:/temp/users-guide-resources/NorthwindLogo.gif");

//get layout data as a string
string stringLayoutData = File.ReadAllText("c:/temp/users-guide-resources/SimpleReportWithCoverPage.json");
LayoutDataResource layoutTwo = new LayoutDataResource(stringLayoutData);
//get dlex from cloud storage
pdf.AddDlex("samples/users-guide-resources/SimpleReportWithCoverPage.dlex", layoutTwo);

return pdf;
Source: InstructionsExample.cs
info

Refer to DlexLayoutObjectExample in the dotnet-client-examples (hhttps://github.com/dynamicpdf-api/dotnet-client-examples/blob/main/DynamicPdfClientLibraryExamples/Examples/InstructionsExample.cs) for an example using serializable objects as layout data.

ImageInput​

Use an ImageInput to process and add an image to a PDF that is returned from the pdf endpoint. 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.

The ImageInput class has the following two constructors. Note that when using the constructor that takes a string, it expects the relative path in your DynamicPDF Cloud Storage and not a local path. Use the ImageResource class for local images.

Constructors​

public ImageInput(ImageResource resource);
public ImageInput(string cloudResourcePath);
Source: ImageInput.cs

Properties​

The ImageInput class provides the following properties for customizing the outputted PDF.

public float? ScaleX { get; set; }
public float? ScaleY { get; set; }
public float? TopMargin { get; set; }
public float? LeftMargin { get; set; }
public float? BottomMargin { get; set; }
public float? RightMargin { get; set; }
public float? PageWidth { get; set; }
public float? PageHeight { get; set; }
public bool? ExpandToFit { get; set; }
public bool? ShrinkToFit { get; set; }
public Align Align { get; set; }
public VAlign VAlign { get; set; }
public int? StartPage { get; set; }
public int? PageCount { get; set; }
Source: ImageInput.cs

ImageResource​

Use the ImageResource class when working with local resources. This class has constructors that accept a file path, a byte array, or a Stream.

public ImageResource(string filePath, string resourceName = null);
public ImageResource(byte[] value, string resourceName = null);
public ImageResource(Stream data, string resourceName = null);
Source: ImageResource.cs

Example​

The following example illustrates using the image input type to get an image as a file, as binary, and then from DynamicPDF Cloud Storage.

Pdf pdf = new Pdf();
//get image from local system
ImageResource ir = new ImageResource("C:/temp/users-guide-resources/A.png");
pdf.AddImage(ir);
//get Image as binary from local system
ImageResource ir2 = new ImageResource(File.ReadAllBytes("C:/temp/users-guide-resources/B.png"));
pdf.AddImage(ir2);
//get image from cloud storage
pdf.AddImage("samples/users-guide-resources/C.png");
return pdf;
Source: InstructionsExample.cs

HtmlInput​

Use an HtmlInput class to process and add HTML to a PDF that is returned from the pdf endpoint.

info

DynamicPDF API fully supports HTML 5 and CSS but does not support JavaScript.

caution

​ An embedded base path must be a resource publicly accessible via HTTP.

The HtmlInput class has one constructor that takes an HtmlResource, a basepath (if it exists), PageSize, PageOrientation, and margins as a float.

Constructor​

public HtmlInput(HtmlResource resource, string basepath = null, PageSize size = PageSize.Letter, PageOrientation orientation = PageOrientation.Portrait, float? margins = null);
Source: HtmlInput.cs
info

The HtmlInput class only accepts local resources and only accepts raw HTML strings.

Properties​

The HtmlInput class has the following properties for customizing the format of the created PDF.

public string BasePath { get; set; }
public float? TopMargin { get; set; }
public float? LeftMargin { get; set; }
public float? BottomMargin { get; set; }
public float? RightMargin { get; set; }
public float PageWidth { get; set; }
public float PageHeight { get; set; }
public PageSize PageSize { get; set; }
public PageOrientation PageOrientation { get; set; }
Source: HtmlInput.cs

HtmlResource​

The HtmlResource class constructor only accepts raw HTML strings

Constructors​
public HtmlResource(string html, string resourceName = null)
Source: HtmlResource.cs

Example​

The following example illustrates using an HTML file to create a PDF.

HtmlResource resource = new HtmlResource(System.IO.File.ReadAllText(basePath + "products.html"));
pdf.AddHtml(resource);
Source: InstructionsExample.cs
tip

Although an embedded CSS stylesheet must be accessible via HTTP, an easy workaround is to replace the <link> tag content with the stylesheet's content.

tempHtml = File.ReadAllText(basePath + "example.html");
tempCss = File.ReadAllText(basePath + "example.css");
    
StringBuilder sb = new StringBuilder();
sb.Append(tempHtml.Substring(0, tempHtml.IndexOf("<link")));
sb.Append("<style>" + tempCss + "</style>");

tempHtml = tempHtml.Substring(tempHtml.IndexOf("<link"));
sb.Append(tempHtml.Substring(tempHtml.IndexOf("/>") + 2));

HtmlResource resource = new HtmlResource(sb.ToString());
pdf.AddHtml(resource, null, PageSize.Letter, PageOrientation.Portrait, 1F);
Source: PdfHtmlCssWorkAroundExample

WordInput​

Use an WordInput class to process and add a Word document to a PDF that is returned from the pdf endpoint.

Constructor​

The WordInput class has one constructor that takes a WordResource, PageSize, PageOrientation, and margins.

public WordInput(WordResource resource, PageSize size = PageSize.Letter, PageOrientation orientation = PageOrientation.Portrait, float? margins = null);
Source: WordInput.cs

Properties​

The WordInput class has the following properties.

//Gets or sets the top margin.
public float? TopMargin { get; set; }
//Gets or sets the left margin.
public float? LeftMargin { get; set; }
//Gets or sets the bottom margin.
public float? BottomMargin { get; set; }
//Gets or sets the right margin.
public float? RightMargin { get; set; }
//Gets or sets the page width.
public float PageWidth { get; set; }
//Gets or sets the page height.
public float PageHeight { get; set; }
//Gets or sets the page size.
[JsonIgnore]
public PageSize PageSize { get; set; }
//Gets or sets page orientation.
[JsonIgnore]
public PageOrientation PageOrientation { get; set; }
Source: WordInput.cs

WordResource​

The WordResource class has three overloaded constructor allowing a file to be uploaded from a filepath, a byte array, or a stream.

Constructors​

The WordResource class has one constructor that takes a WordResource, PageSize, PageOrientation, and margins.

public WordResource(string filePath, string resourceName = null);
public WordResource(byte[] value, string resourceName);
public WordResource(Stream data, string resourceName);
Source: WordResource.cs
info

The Word input type only supports Word documents on your local system.

Example​

The following example illustrates creating a PDF from a Word document.

Pdf pdf = new Pdf();
WordResource wordResource = new WordResource(basePath + "Doc1.docx");
WordInput word = new WordInput(wordResource);
word.PageWidth = 300;
word.PageHeight = 200;
word.TopMargin = 10;
word.BottomMargin = 10;
word.RightMargin = 40;
word.LeftMargin = 40;
pdf.Inputs.Add(word);
return pdf;
Source: InstructionsExample.cs

ExcelInput​

Use an ExcelInput class to process and add an Excel document to a PDF that is returned from the pdf endpoint.

Constructor​

The ExcelInput class has one constructor that takes a ExcelResource, PageSize, PageOrientation, and margins.

public ExcelInput(ExcelResource resource, PageSize size = PageSize.Letter, PageOrientation orientation = PageOrientation.Portrait, float? margins = null);
Source: ExcelInput.cs

Properties​

The ExcelInput class has the following properties.

//Gets or sets the top margin.
public float? TopMargin { get; set; }
//Gets or sets the left margin.
public float? LeftMargin { get; set; }
//Gets or sets the bottom margin.
public float? BottomMargin { get; set; }
//Gets or sets the right margin.
public float? RightMargin { get; set; }
//Gets or sets the page width.
public float PageWidth { get; set; }
//Gets or sets the page height.
public float PageHeight { get; set; }
//Gets or sets the page size.
[JsonIgnore]
public PageSize PageSize { get; set; }
//Gets or sets page orientation.
[JsonIgnore]
public PageOrientation PageOrientation { get; set; }
Source: ExcelInput.cs

ExcelResource​

The ExcelResource class has three overloaded constructor allowing a file to be uploaded from a filepath, a byte array, or a stream.

Constructors​

The ExcelResource class has one constructor that takes a ExcelResource, PageSize, PageOrientation, and margins.

public ExcelResource(string filePath, string resourceName = null);
public ExcelResource(byte[] value, string resourceName);
public ExcelResource(Stream data, string resourceName);
Source: ExcelResource.cs
info

The excel input type only supports Excel documents on your local system.

Example​

The following example illustrates creating a PDF from a Excel document.

Pdf pdf = new Pdf();
pdf.ApiKey = apiKey;
pdf.AddExcel(new ExcelResource(basePath + "/sample-data.xlsx"));
PdfResponse pdfResponse = pdf.Process();
Source: ExcelConversion.cs

PageInput​

Use a PageInput to create, process, and add a PDF page to a PDF that is returned from the pdf endpoint. Also use this input to create a form.

tip

This input creates only single-page PDFs and is intended for cover-pages and other simple PDFs. See the Designer documentation for more information on using Designer to create PDF documents/reports.

When using this input you place one or more elements on the page to create the PDF. The Add Text, Images, Lines, and Rectangles to PDF's solution provides an illustrative example.

info

Refer to the CloudAPI Instructions documentation for examples illustrating fonts, Acroform elements, outlines, and adding other elements to a page to create PDFs using the page input.

When creating a PDF page from scratch, use the PageInput class. But you can only create a single-page PDF using PageInput. Use DynamicPDF Designer to create more complex, multi-page PDF documents.

Constructors​

The PageInput class has the following constructors.

public PageInput(float pageWidth, float pageHeight);
public PageInput(PageSize size = PageSize.Letter, PageOrientation orientation = PageOrientation.Portrait, float? margins = null);
Source: PageInput.cs
tip

If creating complex PDFs, it is easier to use Designer to create a template that creates a PDF rather than using the PageInput class.

Properties​

The PageInput class has the following properties for customizing a page.

public float? PageWidth { get; set; }
public float? PageHeight { get; set; }
public float? TopMargin { get; set; }
public float? LeftMargin { get; set; }
public float? BottomMargin { get; set; }
public float? RightMargin { get; set; }
public PageSize PageSize { get; set; }
public PageOrientation PageOrientation { get; set; }
public List<Element> Elements { get; }
Source: PageInput.cs

Building a page from scratch provides most of the functionality of our flagship server/desktop product, DynamicPDF Core Suite. The client libraries provides numerous classes for creating your PDF using PageInput.

Element Classes
AztecSymbolSizeLineElement
CompactionMsiBarcodeCheckDigitMode
DataMatrixEncodingTypePageNumberingElement
DataMatrixFunctionalCharacterRectangleElement
DataMatrixSymbolSizeTextElement
ElementValueType
ElementPlacementStackedGs1DataBarType
ElementTypeQrCodeElement
ErrorCorrectionQrCodeEnc1
Barcode Elements
AztecBarcodeElementDim2BarcodeElement
Code11BarcodeElementGs1BarcodeElement
Code12BarcodeElementlata25BarcodeElement
Code128BarcodeElementMsiBarcodeElement
Code25BarcodeElementPdf47BarcodeElement
Code39BarcodeElementTextBarcodeElement
Code93BarcodeElement
DataMatrixBarcodeElement
info

Refer to the CloudAPI Instructions documentation for examples illustrating using many of the above classes to create PDFs using the page input.

PdfInput​

Use a PdfInput to create, process, and add a PDF to a PDF that is returned from the PDF endpoint. You usually use this input with one or more other inputs types to merge into a combined PDF.

The PdfInput has the following constructors for adding a PDF to the pdf endpoint.

Constructors​

public PdfInput(string resourceName);
public PdfInput(PdfResource resource, MergeOptions options = null);
public PdfInput(string cloudResourcePath, MergeOptions options = null);
Source: PdfInput.cs
  • Load a PDF using the resource's name in cloud storage.
  • Load a PDF from a PdfResource.
  • Load a PDF from a PDF in cloud storage's relative path.

Properties​

The PdfInput has the following three properties that allow customizing which pages to take from a PDF.

public MergeOptions MergeOptions { get; set; }
public int? StartPage { get; set; }
public int? PageCount { get; set; }
Source: PdfInput.cs

PdfResource​

The PdfResource allows obtaining a PDF from your local system rather than DynamicPDF Cloud Storage.

Constructors​

The PdfResource class has the following three constructors. The constructors allow using a file path, a byte array, or a Stream.

public PdfResource(string filePath, string resourceName = null);
public PdfResource(byte[] value, string resourceName = null);
public PdfResource(Stream data, string resourceName = null);
Source: PdfResource.cs

Example​

The following example illustrates three different ways to get a PDF and then merges them into a combined PDF.

Pdf pdf = new Pdf();

//get pdf from local file system
pdf.AddPdf(new PdfResource("c:/temp/users-guide-resources/DocumentA.pdf"));
            
// get pdf from bytes
PdfResource resource = new PdfResource(File.ReadAllBytes("c:/temp/users-guide-resources/DocumentB.pdf"));
pdf.AddPdf(resource);

//get pdf from cloud storage
pdf.AddPdf("samples/users-guide-resources/DocumentC.pdf");
return pdf;
Source: InstructionsExample.cs