# PDF Templates

PDF Templates is a special class that contains all the template instances you create using the PDF Template Editor. Each instance holds the specific `fillTemplate` function for its corresponding layout. For a full guide on how to visually design a template, please refer to the main [PDF Template Editing](/app-builder/build-frontend/pdf-template-editor.md) article. This document focuses on how to use the function in your backend logic.

## fillTemplate

The `fillTemplate` function is the engine that programmatically merges your application's data with a pre-designed PDF layout to generate a finished document.

### Input

The function has two inputs: a required data object and an optional configuration object.

* **Values** (required): A standard data object with key-value pairs. The keys in this object (e.g., `firstName`, `orderDate`) must exactly match the variable names you configured for the placeholders in the Template Editor.
* **Options** (optional): A JSON object for configuring the function's behavior. It has one property:
  * `showEmptyVariables`: Set to `true` to display `null` or `undefined` on the final PDF if a placeholders value is undefined in the data object. Defaults to `false`, which shows nothing for empty values.

**Example:**

```yaml
#values
name: John
surname: Doe
signature: data:image/png;base64,iVBORw0KGgoAAAANSUhEUg...
#options
showEmptyVariables: true
```

### Output

The function provides the finished, populated PDF document as a Base64 encoded string. While designing your logic, the function output itself will show a preview of the rendered PDF with your template's layout. The output can be used to store in a database, visualize in a media view widget, send in an email or in any other way you like.

The function provides the finished, populated PDF document as a Base64 encoded string. While designing your logic, the function block itself will show a preview of the rendered PDF with your template's layout. The output can be used to store the document in a [database](/app-builder/build-backend/function-explorer/storage/relational-database.md), visualize it in the [media view widget](/app-builder/build-frontend/widgets/display-widgets/media-view.md), send it as an [email](/app-builder/build-backend/function-explorer/connectors/email.md) attachment, or process it further in any other way your application requires.

<figure><img src="/files/5Ch9z6UJOv3PAU5a73bf" alt=""><figcaption><p>A simple example of a fillTemplate function</p></figcaption></figure>

{% hint style="info" %}

## Important Notes

* Data is Overwritten: Each execution of the `fillTemplate` function generates a brand new document and completely overwrites all fields.
* **Fill All at Once**: The function is designed to populate the entire template in a single operation.
* **Complex Data**: For templates with many fields, it is a best practice to first gather all the necessary data into a single, structured object before passing it to the function.
* **User-Specific Documents**: Each output is a separate document isolated for the user session that triggered the function.
  {% endhint %}

## Full Tutorial

To see the PDF Templates class in action, follow our complete step-by-step guide where we build a dynamic acceptance report from start to finish.

[From Data to Document: Automating PDF Reports](/tutorials/app-templates/automating-pdf-reports.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.heisenware.com/app-builder/build-backend/function-explorer/utilities/pdf-templates.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.