# PDF Forms
## Creating PDF Forms
To get started creating PDF Forms:
1. Navigate to the **Forms** section within a Project.
2. Click the **+New Form** button.
3. Select the **PDF Form** option
{% hint style="info" %}
A standard page size (like A4) is required to upload a PDF. Non-Standard sizes will not be accepted and will result in an error. To fix this, re-save the PDF as a file with standard page sizes.
{% endhint %}
4. Click the **Upload PDF** button. Use the file management UI to find and select any PDF on the local machine.\
After selecting a PDF File, the platform will process and upload the PDF to the Form.io portal.
After the PDF Form is uploaded, the PDF will open inside of the Form Builder.\
Here, users can drag and drop overlay components onto the PDF. The PDF form will function like other forms within the platform. This enables form builders to incorporate PDFs into staging, team workflows, and form versioning, all while utilizing an intuitive drag-and-drop interface.
{% hint style="info" %}
Importing a PDF First Form using a Form Embed URL or a project JSON file will automatically migrate and upload the associated PDF file. There is no need to upload the PDF file after the Form JSON has been imported.
{% endhint %}
## PDF Components
Within the builder, form builders are presented with a range of overlay component choices.\
Many of these components behave the same way as they would on web forms, but certain components have been adjusted in functionality to better suit the context of PDF forms.
The list below outlines the components available and highlights the variations in settings between PDF forms and web forms. It's important to note that these changes pertain exclusively to PDF forms and do not relate to web form submissions that are downloaded as PDFs.
For documentation on the standard behavior of the available components, refer to the following documentation:
* [**Text Field**](https://help.form.io/userguide/form-building/form-components/basic-components#text-field)
* [**HTML**](https://help.form.io/userguide/form-building/form-components/layout-components#html-element)
* [**Email**](https://help.form.io/userguide/form-building/form-components/advanced-components#email)
* [**Text Area**](https://help.form.io/userguide/form-building/form-components/basic-components#text-area)
* [**Number**](https://help.form.io/userguide/form-building/form-components/basic-components#number)
* [**Phone Number**](https://help.form.io/userguide/form-building/form-components/advanced-components#phone-number)
* [**Password**](https://help.form.io/userguide/form-building/form-components/basic-components#password)
* [**Date & Time**](https://help.form.io/userguide/form-building/form-components/advanced-components#date-and-time)
* [**Checkbox**](https://help.form.io/userguide/form-building/form-components/basic-components#check-box)
* [**Currency**](https://help.form.io/userguide/form-building/form-components/advanced-components#currency)
* [**Select**](https://help.form.io/userguide/form-building/form-components/basic-components#select)
* [**File**](https://help.form.io/userguide/form-building/form-components/premium-components#file)
* [**Signature**](https://help.form.io/userguide/form-building/form-components/premium-components#signature)
To understand how these components behave on PDF-First forms, refer to the section [#component-behavior-unique-to-pdf-forms](#component-behavior-unique-to-pdf-forms "mention")of this document.
### **Adding Overlay Components**
Add overlay components to the PDF Form by using the drag-and-drop builder. The dropped position of the component will be the position the overlay is saved to on the PDF form. Overlay components will display their component name( E.G. texfield) within the overlay box to indicate the component type on the form.
### **Positioning Overlay Components**
To reposition an overlay field, click and drag the field to a new position on the form. To manually resize the component, hover over the component and click and hold the blue sizing box at the bottom right of the overlay. While holding, the user can resize the height and width of the component while mainting its position.
{% hint style="info" %}
Click the + magnifying icon on the PDF form to zoom in for pixel perfect positioning when placing the overlay components. =
{% endhint %}
### **Component Setting Changes**
The following component settings are not applied or recommended when configuring the PDF overlay settings and rendering the PDF form. These settings have the potential to interfere with form due to their dynamic characteristics and static nature of a PDF:
* Label
* Label position
* Description
* Tooltip
* Multiple value
Using any of the above component settings on a PDF-first form may result in failures, display irregularities, or unexpected behavior.
{% hint style="info" %}
Use the Placeholder setting or an HTML component as an alternative to the Label.
{% endhint %}
### Component Behavior Unique to PDF Forms
It is important to note that the following components and behaviors differ from the standard behavior on a web form.
### Input Fields
Input fields are components the end user will interact with to input data. These include:
* Text
* Email
* Text Area
* Number
* Phone number
* Password
* Date/Time
The vertical size of the component dictates the font size of the text entered by the user. To ensure you have font size unity across all of your overlay fields, use the [**PDF Overlay**](https://help.form.io/userguide/form-building/form-components/component-settings#pdf-overlay) height setting to ensure each of your components carries the same text size and field height. Alternatively, you can use the [**PDF Font Size** ](#pdf-font-size)setting on the form to universally set all field text sizes on the form regardless of the component height.
### Checkboxes and Radios
A major component of any PDF form are checkbox or radio interface for selecting options. The PDF system incorporates the single **Checkbox** component to handle both Radio (mutually exclusive) and Checkbox interfaces. Users have the ability to style each checkbox and radio to match the uploaded PDF.
#### Checkbox
The use of a checkbox is to have a singular select capability. This is typically used for a control such as an “I agree” statement where they are providing a single yes/no answer. To add a checkbox to your form, drag and drop the Checkbox component and then resize it according to the checkbox outline as follows.
By default, the label will be hidden for all checkbox inputs, so simply type the name of the Label for this checkbox and ensure the API key is what you would like to have saved for the data in this checkbox.
Finally, you can move and resize the checkbox to the appropriate size of the checkbox on the PDF.
#### Checkbox - Radio
Radio buttons are used to allow for a mutually exclusive selection between different elements on the form. A good example of this is if you wish to have a Marital status selection on your PDF form where they can toggle between “Married” or “Single” and it would deselect the one or the other as you use the control. To create a new Radio interface, you will need to drag each “radio” checkbox onto the PDF form independently. This can be done with the **Checkbox** component.
Once you drag and drop the Checkbox component and see the edit modal, you will then configure the Radio component by choosing the **Input Type** as **Radio**. You will then see two text boxes show up called **Radio Key** and **Radio Value**. For these, you will put the “key” of the radio that will store the data (such as “maritalStatus”) and the “value” is the value of that key when this checkbox is selected (like “married” or “single”)
#### Radio and Checkbox Styles
By default, the styles for the checkbox and radio buttons are a blue highlighted square. This can be customized by editing the **Custom CSS Class** on each of the checkbox components on the PDF form. The Form.io PDF Viewer utilizes a Checkbox style system called [**Pretty Checkbox**](https://lokesh-coder.github.io/pretty-checkbox/) to perform the styles. The following styles can be applied to every Radio and Checkbox component.
Here is an example of providing Custom CSS Classes to a PDF Checkbox component.
**Shape**
The following classes will alter the shape of the checkbox and radio input.
| **Class** | **Description** |
| --------- | -------------------------------------------------------------------- |
| p-round | Turns the square checkbox into a circle (good for Radio interfaces). |
| p-curve | Turns the square checkbox into a rounded square |
**Fill**
The following classes will alter the fill thickness of the input when a Checkbox / Radio is selected.
| **Class** | **Description** |
| --------- | -------------------------------------------------------- |
| p-fill | Fills up the whole checkbox with the desired color. |
| p-thick | Turns the outline into a thick outline with small middle |
Here is an example of these classes applied.
#### **Color**
The color of the fill can be controlled with the following classes.
| **Class** | **Description** |
| --------- | ---------------- |
| p-primary | Blue color. |
| p-success | Green color. |
| p-info | Light Blue Color |
| p-warning | Orange Color |
| p-danger | Red Color |
Here is an example of colors applied.
**Type**
The type of input can also be changed to a “switch” input using the following.
| **Class** | **Description** |
| --------- | --------------------------------------- |
| p-switch | Turns the checkbox into a switch input. |
The Switch has 3 different shapes you can set by adding the following class
| **Class** | **Description** |
| --------- | ----------------------------------------------- |
| p-outline | Highlights switch outline when clicked |
| p-fill | Fills switch when clicked |
| p-slim | Slims the UI and highlights switch when clicked |
In addition to the [**Pretty Checkbox**](https://lokesh-coder.github.io/pretty-checkbox/) styles, the PDF Viewer also utilizes the [**Font Awesome**](https://fontawesome.com/v4/icons/) icon library to add or change the icon displayed on the Checkbox when clicked. Add the **icon-** to the Custom CSS Field to set your class then add the icon text from the Font Awesome library.
Here are some common examples of icons you may want to apply using the **Font Awesome** library:
| Class | Example |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| icon-checkbox |  |
| icon-thumbs-up |  |
| icon-edit |  |
| icon-file |  |
{% hint style="info" %}
Use both the [**Font Awesome**](https://fontawesome.com/v3/icons/) icon library and [**Pretty Checkbox**](https://lokesh-coder.github.io/pretty-checkbox/) CSS Styling to create customized Checkbox and Radio components
{% endhint %}
#### Show checkbox/radio background setting
In [**Form Settings**](#pdf-form-settings), there is an option to show or hide the radio and checkbox component background. This setting gives checkbox and radio components a background and borders when viewing the PDF First Form submission.
## Removing a PDF
To remove a PDF from a form, Edit the form to enter the Form Builder. Click the Remove button next to the Display As dropdown and Save the form to remove the PDF. Users can then switch the PDF to a Webform by clicking the Display As dropdown and seleting Form. Although the PDF has been removed from the Form, the PDF still exists within the PDF server and will count against the allocated PDF within the license limits and will need to be removed from the [**PDF File Managment**](#pdf-file-management) section of the project.
## PDF File Management
PDF files are managed by clicking the PDF tab from the left-hand navigation bar within the Project. Here users can can see PDFs that have been uploaded to the Stage along with the PDF ID and what Form they have been uploaded and connected to. When a PDF is removed from a Form, a trash can icon will appear in the Operations column where you can remove the PDF from the project and server. This allows the user to free up
## Submitting and Viewing PDF Data
With a PDF form constructed, users can now begin to interact with submitting and viewing form data. Click the `Use` (or launch) tab to begin.
{% hint style="info" %}
The PDF Server itself does not store submission data as a part of the PDF generation process.
{% endhint %}
Complete the form and click `Submit` at the bottom to post the submission to the projects database.
Selecting the `Data` tab, users can view all submissions within the submission grid and can interact with individual submissions.
Notice that the data displayed in the table above is overlaid on the PDF.
Provided the active user has permission, a printable copy of the PDF form and its data can be exported.
This power extends to simple form submissions as well. For example, if the traditional version of the form is filled out through an email or some other service, users can still print the submission in PDF form.
## Hybrid PDF Forms
In many cases, you may wish for your end user to submit the form as a regular webform using either the Form or Wizard display, but then print the PDF as a PDF Submission (shown above). This kind of hybrid approach is also supported by Form.io by first changing the Display of any PDF Form and then saving it as the following illustrates.
Once you Save and then use this form, you will be presented with the regular webform (which is what your users will see when they fill out the form). However, there is one big difference. The original PDF is still attached to the form which lets the submission PDF generation process know that it should use the underlying PDF as a background to the data when a submission is made. This looks like the following when you print a PDF.
Generates the following submission PDF
This capability enables you to have the best of both worlds. Have users fill out the form as a regular webform, but print the submissions as pixel-perfect PDF output.
## Nested PDF Forms
At times, you may want to include a pre-existing PDF form into another form. Use the [**Nested Form**](https://help.form.io/userguide/form-building/form-components/premium-components#nested-form) component inside Webforms or a page inside a Wizard form. Setting up a nested PDF Form follows the same steps and guidelines as any other Nested Form.
## Webform Submission PDFs
In addition to creating and uploading existing PDF documents, the Form.io platform can be used to generate PDFs from webform submissions. Viewing any webform submission will allow you to download the submission as a PDF by clicking the PDF download icon.
To generate a PDF, navigate to any form within your project and create a new submission. After submitting, you will be redirected to a submission view page where you can click the **PDF** icon to download the submission.
Once the form is created, you can now create a new submission by clicking on **Use** button and then submitting the form you just created.
Clicking this icon will open the submission in a new tab where you can download or print the submission to PDF.
Once you fill out the form and create a new submission, you will be redirected to a submission view page. Click the **PDF icon** at the top right of the view page to download a PDF version of the submission.
Navigate to the Data tab of any Form or Resource and view any submission to access the PDF download option.
## Page Breaks
Now that you are able to print a submission as a PDF, you may also wish to introduce page breaks into the PDF download. To accomplish this, first, edit your form, and then click on the element you wish to push down to a different page. In this example, edit the **Team Information** panel. Within the settings, introduce a special class to the element called **page-break-before**. This tells the PDF renderer where to introduce new page breaks.
Now make sure to save your form.
Now, you can click on the download PDF button for any of the submissions, and it will introduce a page break before the element you provided.
{% hint style="info" %}
Certain layout components like HTML and Panel will span across a page when downloading to PDF. This is intended behavior and prevents unnecessary blank space or blank pages within your PDF download. Please use the page-break-before element if a page break is needed.
{% endhint %}
## Form.io Default Viewer
PDF downloads of basic forms submissions like Web and Wizard forms are viewed using a packaged application called Form.io Viewer. For our SaaS offering, the current viewer is hosted @ . If you wish to make changes to the theme based on [**Bootswatch Themes**](https://bootswatch.com/3/), then you can use the following format
{% hint style="info" %}
Submission PDF downloads for PDF First forms do **not** utilize the formio-viewer, but instead, utilize the formio-pdf module for downloading PDFs for PDF-first forms.
{% endhint %}
```
https://formio.github.io/formio-viewer/dist?theme=paper
```
Like so…
You can also change the theme using the **PDF Theme** to select an available [Bootswatch](https://bootswatch.com/) theme in the **PDF Settings** section:
Bootswatch themes are provided by a third party. They may be updated to match ongoing Bootstrap development. To continue using a fixed version of Bootswatch and avoid potential styling changes, consider implementing a [#custom-pdf-viewer](#custom-pdf-viewer "mention") that uses a fixed version.
### Viewer Parameters
There are also some parameters that you can pass to the viewer that is hosted by Form.io for the SaaS offering to alter the output of the generated PDF. These parameters can be provided a GET query parameters to the viewer. For example, to not show the header for the viewer, you can provide the following.
```
https://formio.github.io/formio-viewer/dist?theme=paper&header=0
```
The following viewer parameters are supported.
| Setting | Description | Example |
| ------- | --------------------------------------------- | ---------- |
| theme | The Bootswatch 3 theme to provide to the pdf. | theme=yeti |
| header | If you wish to hide the header | header=0 |
### PDF Generation Parameters
In addition to there being viewer parameters, there are also parameters that you can provide to the end of the PDF generation API. For example, to alter the margins of the generated PDF document, you can provide the following to the PDF generation url.
```
https://yourproject.form.io/yourform/submission/[SUBMISSION_ID]/download?token=TOKEN&margin=20,20,20,20
```
The accepted PDF parameters are listed in the table below.
| Setting | Description | Example |
| ------- | ---------------------------------------------------------------- | ------------------ |
| margin | The margin as provided like a CSS margin (top,left,bottom,right) | margin=20,20,20,20 |
| scale | The scale to provide to the generated PDF | scale=0.6 |
| width | The width of the viewport when generating the PDF | width=800 |
| height | The height of the viewport when generating the PDF | height=1100 |
| view | To show the submission in “viewAsHtml” mode | view=1 |
### **Custom PDF Viewer**
By default, the submission PDFs that are generated use a default Form viewer application to render the submissions. For the SaaS offering, this is the hosted viewer described above. For Self Hosted Deployments, this Viewer Application is packaged within the formio-enterprise container and resides in your own self-hosted environment.
To satisfy custom requirements, a **Custom PDF Viewer** application can be used, by modifying the default, to render the submissions for PDF generation. This is very helpful to provide custom PDF templates, or maybe even create submissions PDFs that introduce custom elements into the PDF generation. To achieve this, start by forking the Default Form Viewer found @
[**https://github.com/formio/formio-viewer**](https://github.com/formio/formio-viewer)
Once you download this Viewer application, make sure you install dependencies with the following command:
```
npm install
```
Now, make any modifications needed to the application. For example, the [**Paper Theme**](https://bootswatch.com/3/paper/) from Bootswatch can be used by the Viewer by making the following change to the `src/index.html`
**src/index.html**
```
document.write('');
```
You can now compile this application using the following command.
```
npm run build
```
This will create a **dist** folder, which must then be launched to your own hosting service. Once this is hosted, form settings can be edited. Then, introduce a new **Custom Property** called **viewer** and set the value to the URL of the custom viewer application as seen below.
Please [**Click Here**](https://help.form.io/deployments/deployment-guide/pdf-server) for more information
Another way to configure the PDF viewer is by using a **PDF Viewer URL** field in the **PDF Settings** section.
Once you save, and then go back to submission and download that submission, you will notice that the PDF download now uses your own custom viewer application to render the submission PDF.
To make all PDFs generated by a deployed PDF server use this customized Viewer Application, set the Environment Variable `FORMIO_VIEWER` within your Docker container run command.
```
docker run -itd \
-e "FORMIO_SERVER=https://formio.yourdomain.com" \
-e "FORMIO_PROJECT=59b7b78367d7fa2312a57979" \
-e "FORMIO_PROJECT_TOKEN=wi83DYHAieyt1MYRsTYA289MR9UIjM" \
-e "FORMIO_PDF_PROJECT=https://formio.yourdomain.com/yourproject" \
-e "FORMIO_PDF_APIKEY=is8w9ZRiW8I2TEioY39SJVWeIsO925" \
-e "FORMIO_VIEWER=https://formio.github.io/formio-viewer/dist?theme=paper" \
-e "FORMIO_S3_KEY=[S3 KEY]" \
-e "FORMIO_S3_SECRET=[S3 SECRET]" \
-e "FORMIO_S3_BUCKET=[S3 BUCKET]" \
-e "FORMIO_S3_REGION=[S3 REGION]" \
--restart unless-stopped \
--name formio-files-core \
-p 80:4005 \
formio/formio-files-core;
```
Please [**Click Here**](https://help.form.io/deployments/deployment-guide/pdf-server#pdf-server-environment-variables) for more information.
### Mounting Custom PDF Viewer onto PDF Server
The fastest way to get your PDF Viewer onto your local deployment is to mount it onto the PDF server container. You will be using [bind mounts](https://docs.docker.com/storage/bind-mounts/) to replace PDF servers form-viewer with your custom form-viewer. To get started open up your project containing your `docker-compose.yml` file used to run your local deployment. Your file structure should look something like the following
```
local
|- /conf.d
|- default.conf
|- /data
|- /db
|- /minio
|- .env
|- docker-compose.yml
```
Add a new directory to your `local project` called /viewer and copy the files within your `formio-viewer project` /dist folder to the /viewer folder.
```
local
|- /conf.d
|- default.conf
|- /data
|- /db
|- /minio
|- .env
+ |- /viewer
+ |- /assets
+ |- /fonts
+ |- /lib
+ |- index.html
|- docker-compose.yml
```
Now that your pdf viewer files are within your local deployment project you need to mount the files within the PDF server container file system. To do this open up your docker-compose.yml and add the following
```
...
pdf-server:
image: formio/pdf-server
restart: no
mem_limit: 2048m
links:
- mongo
- minio
ports:
- "4005:4005"
environment:
MONGO: mongodb://mongo:27017/formio
FORMIO_S3_SERVER: minio
FORMIO_S3_PORT: 9000
FORMIO_S3_BUCKET: formio
FORMIO_S3_KEY: CHANGEME
FORMIO_S3_SECRET: CHANGEME
FORMIO_PDF_PORT: 4005
env_file:
- data/.env
volumes:
+ - "./viewer:/src/node_modules/@formio/viewer/dist"
...
```
`"- "./viewer:/src/node_modules/@formio/viewer/dist"` takes the files in /viewer on your host machine and adds them to your containers file system under the path `/src/node_modules/@formio/viewer/dist`
Run the command `docker compose up -d` and try downloading a PDF submission. You should now see the pdf being rendered with your custom formio-viewer
### Formio-Viewer Repository
The [formio-viewer](https://github.com/formio/formio-viewer/) repository is where you will design and build your own custom pdf viewer. Fundamentally, the purpose of the formio-viewer is to...
* Replace formio components with custom components
* Add custom css to index.html
* Call the window\.setForm function to create a new form and then set the submission of that form in index.html
When these tasks are done the PDF server will then convert your index.html to a PDF
#### Replacing formio components
To replace formio components with your own custom components navigate to the `/src/components/` directory. This directory is where you will override and add new functionality to existing formio components. In this example you will be overriding the edit grid behavior to expand its view to show all the components nested within. Start by creating a new javascript file in the /components directory called ViewerEditGrid.js and add the following code
**Note:** It is the convention when replacing components to prefix the replaced component with `Viewer`
```
import EditGridComponent from "formiojs/components/editgrid/EditGrid";
export default class ViewerEditGrid extends EditGridComponent {
constructor(...args) {
super(...args);
// Disable edit grid header rendering.
this.component.templates.header = ""
// If we do not have a submission, add an initial row to all EditGrids
if (this.root && !this.root.submissionSet) {
this.component.openWhenEmpty = true;
}
}
// Ensure all rows open.
isOpen() {
return true;
}
}
```
[Click here](https://help.form.io/developers/form-development/custom-components) to learn more about creating custom components
Now you need to replace the edit grid component with the new viewer edit grid. Open the src/renderer.js file and add the following code
```
import {Formio} from 'formiojs/formio.form.js';
import Flatpickr from 'flatpickr';
window.flatpickr = window['flatpickr-css'] = Flatpickr;
import './components/ViewerCalendar';
import ViewerDateTime from './components/DateTime';
import ViewerTextField from './components/TextField';
+ import ViewerEditGrid from "./components/ViewerEditGrid";
Formio.Components.setComponent('datetime', ViewerDateTime);
Formio.Components.setComponent('textfield', ViewerTextField);
+ Formio.Components.setComponent('editgrid', ViewerEditGrid)
export {Formio};
```
`Formio.Components.setComponent('editgrid', ViewerEditGrid)` sets the edit grid component to the new viewer edit grid component. Now all edit grid components will be expanded and have the header removed when rendering onto a pdf
#### Adding custom css
To add custom css to your pdf viewer make changes within the \ tag in the `index.html` file. For example, if you wanted to change the background of your pdf make the following changes within the \
```
You can also do this by adding a CSS file in your `/src/assets` directory.
#### window\.setForm(form, submission, options) function
In `index.html` there is a vital function for converting your form submissions into pdfs called `window.setForm`. This functions job is to create a new form on the page with the `form` and `options` arguments and then set the forms instance to the `submission` argument. This function is called when you go to download your pdf and is key to understanding how your forms will be rendered in your pdf downloads. You do not need to make any changes to this function
#### Building your source code to distribution code
To build your source code there is a script called `build` in the `package.json` file in your project. Run this command by typing `npm run build` in your terminal. This will do the following...
* `gulp build` grabs the necessary CSS, JavaScript, Bootstrap, Formio.js library, etc. needed to render the form submission onto the page and puts them into the /dist directory
* `webpack --config webpack.config.js` will build the `renderer.js` file to /dist/lib/formiojs/formio.form.min.js, bundling all the necessary javascript needed to replace components with viewer components
* `gulp inlinesource` replaces all \
