PDF Generation with PDF Processor

Information

PSPDFKit Processor has been deprecated and replaced by PSPDFKit Document Engine. All PSPDFKit Processor licenses will work as before and be supported until 15 May 2024 (we will contact you about license migration). To start using Document Engine, refer to the migration guide. With Document Engine, you’ll have access to robust new capabilities (read the blog for more information).

Processor allows you to create PDF documents from an HTML file. This is done by supplying a part containing the html key to the POST /build endpoint. The following schema outlines all available options:

type Orientation = 'landscape' | 'portrait';
type PageSize =
	| 'A0'
	| 'A1'
	| 'A2'
	| 'A3'
	| 'A4'
	| 'A5'
	| 'A6'
	| 'A7'
	| 'A8'
	| 'Letter'
	| 'Legal';

// Represents one part that was sent in the multipart request. Should be the
// `name` that was specified for the part.
type MultipartReference = string;

type HTMLPart = {
	html: MultipartReference; // The HTML file passed in the multipart request.
	assets?: Array<MultipartReference>; // All assets imported in the HTML. Reference the name passed in the multipart request.
	layout?: {
		orientation?: Orientation;
		size?:
			| {
					width: number;
					height: number;
			  }
			| PageSize; // {width, height} in mm or page size preset.
		margin?: {
			// Margin sizes in mm.
			left: number;
			top: number;
			right: number;
			bottom: number;
		};
	};
};

The html key, which points to the main HTML file, is mandatory. All other keys are optional.

Referencing Assets

When designing an HTML page, it’s common to split the design into multiple files, such as an HTML file, a CSS file, fonts, and image files. The PDF generation command expects a flat directory structure, so any referenced assets have to reside next to the HTML file and not in subdirectories.

The following shows how you’d send a CSS file that’s referenced in the HTML file:

<!DOCTYPE html>
<head>
	<link rel="stylesheet" href="style.css" />
</head>
<html>
	<body>
		<h1>PDF Generation Header</h1>
		<img src="my-image.jpg" />
	</body>
</html>
@font-face {
	font-family: 'Open Sans';
	src: url('OpenSans-Regular.ttf') format('truetype');
}

h1 {
	font-size: xx-large;
	font-family: 'Open Sans', sans-serif;
}

The request to create a PDF from these assets would look like this:

curl -X POST http://localhost:5000/build \
  -H "Authorization: Token token=secret" \
  -o result.pdf \
  --fail \
  -F page.html=@/path/to/page.html \
  -F style.css=@/path/to/style.css \
  -F my-image.jpg=@/path/to/my-image.jpg \
  -F OpenSans-Regular.ttf=@/path/to/OpenSans-Regular.ttf \
  -F instructions='{
      "parts": [
        {
          "html": "page.html",
          "assets": [
            "style.css",
            "my-image.jpg",
            "OpenSans-Regular.ttf"
          ]
        }
      ]
    }'
Warning

Please note that JavaScript assets currently aren’t supported.

Assets passed in the multipart request must match the name used to reference the file in HTML. For example, if you have an image block, <img src="my-image.jpg">, the data representing the image in the multipart request should have the name my-image.jpg.

Page Layout

The layout object, which is part of the HTML part, allows for customization of the PDF page layout and dimensions. All figures in this object are referenced in millimeters, and all pages take this configuration.

Fillable Forms

PSPDFKit API can also generate PDFs containing fillable form fields from HTML.

Because not all HTML form fields map directly to PDF forms, a subset of form fields is supported. The following table shows how the HTML input element types map to PDF form types.

Input Type PDF Form Field
text Text box
password Text box where all characters are replaced with *
radio Radio button
checkbox Checkbox
select Combo box

All other input types aren’t supported and won’t be converted to PDF form fields.

Form Values

All input values (form values, radio buttons, and checkboxes) are carried over to the form field values in the generated PDF.

Headers and Footers

PSPDFKit API can add custom header and footer sections that are repeated across all pages in the resulting PDF. You can also dynamically display the current page number and page count, as well their styles.

Adding a Header

PSPDFKit API looks for a container element using pspdfkit-header as its ID, defined in your template, and it’ll repeat it at the top of each of the generated pages:

<div id="pspdfkit-header">
	<div class="header-columns">
		<div class="logotype">
			<img class="logo" src="logo.svg" />
			<p>ACME Inc.</p>
		</div>

		<div>
			<p>Always improving.</p>
		</div>
	</div>
</div>

Before generating the PDF, the following CSS is added before any style sheet already defined in the template. We don’t recommend overriding those properties, as it might break the header position:

#pspdfkit-header {
	display: flow-root;
}

The display: flow-root; declaration defines a new block formatting context and suppresses margin collapsing so that any margin defined inside the header is preserved entirely across all pages in the resulting PDF.

Information

If specified, the element with pspdfkit-header as its ID must be the first child of the document’s body.

To add a footer on all pages, define a container element with the pspdfkit-footer ID. It must be the last child of the document’s body:

<div id="pspdfkit-footer">
	<div class="footer-columns">
		<span>10/18/2021</span>
		<span>Page {{ pageNumber }} of {{ pageCount }}</span>
	</div>
</div>

Before generating the PDF, the following CSS will be added before any style sheet already defined in the template. We don’t recommend overriding these properties, as it might break the footer position:

#pspdfkit-footer {
	display: flow-root;
	position: absolute;
	left: 0;
	right: 0;
	bottom: 0;
	box-sizing: border-box;
	width: 100%;
}

The display: flow-root; declaration defines a new block formatting context and suppresses margin collapsing so that any margin defined inside the footer is preserved entirely across all pages.

Displaying the Current Page Number and Page Count

To display the current page number in a header or footer, use the special {{ pageNumber }} token as a placeholder to tell PSPDFKit where to display the value of each page. Similarly, for the total page count, use the {{ pageCount }} token:

<p>
	Page {{ pageNumber }} of
	<strong>{{ pageCount }}</strong>
</p>

When specifying a header and footer, you can make use of any HTML and CSS as usual, and all styles added to the main page will affect the header and footer as expected with regular DOM elements.

You can add images, use custom fonts, set a background, or change font size.

To set a gap between the header and the content, you can use regular CSS techniques, such as specifying a margin-bottom declaration to the #pspdfkit-header selector via CSS.

Similarly, you can also use CSS to set a gap between the content on each page and the footer — for instance, via the margin-top property in the #pspdfkit-footer selector.

Information

The margins that are set to the page layout as part of the generation configuration affect the space between the edges of the generated pages and the header and footer, respectively.