PDF Forms

Introduction
One of the more exciting features of Form.io is the PDF form platform. This system allows you to take any existing PDF form document and upload this into the Form.io platform where it is then converted into a JavaScript powered HTML webform where it can then be utilized in the same way as our standard form renderer. This system provides an elegant alternative to the typical cumbersome PDF email workflow that everyone dreads to receive within their email inbox. With the Form.io PDF platform, the entire PDF process can be consumed on the web while at the same time extracting the data of those PDF's into an API driven interface for easy integrations.
Within every PDF form, you can utilize the following form components from the Form.io platform.
Text
Numbers
Passwords
Select
eSignatures
Email Addresses
Phone Numbers
Date & Time
Currencies
We can see this by first creating a new PDF form.
Creating PDF Forms
To get started creating PDF Forms, we will first click on the New Form link within your project.
On the next page, you will click PDF Form
Next, select Upload PDF and the computers file management system will appear, allowing users to find and select any PDF on their machine. After selection, it may take a moment while the platform uploads and processes the submission. The Larger the file, the longer the processing time.
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. 
After completion, the PDF will display in the PDF builder mode. This will allow for you to drag-and-drop new components as an overlay on top of the PDF form. We can try this out by dragging and dropping a few Text Field components onto the new pdf background as follows.
After you create a few fields, you will now Save the form by clicking the Save Form button. Once saved, the PDF Form will now act like any other form on the platform.
This means users can integrate PDFs with staging, team workflows, and form versioning all while using a simple, drag and drop interface.
PDF Components
Most of the components within a PDF form are very similar to a regular webform components. Some of the components, however, do have a change in behavior that is described below.
Checkboxes and Radios
A major component for any PDF form is the ability to create checkbox or radio interfaces for the selection of items within the PDF. Our PDF system incorporates the single Checkbox component to handle both the Radio (mutually exclusive) and Checkbox interfaces, with addition to 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.
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 see the edit modal, you will then configure the Radio component by chosing 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”)
This will now show up as follows in your form.
Radio and Checkbox Styles
By default, the styles for the checkbox and radio buttons are a blue highlighted square. This can be configured by editing the Custom CSS Class on each of the checkbox components. The PDF viewer uses a Checkbox style system known as Pretty Checkbox to perform the styles. Each of the styles can be established by using special classes within the Custom CSS Class setting. The following styles can be applied to every Radio and Checkbox component.
As an example, you can provide the following classes to turn your Radio’s into a solid green filled circles with the following classes.
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.
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.
Other classes can be provided as follows.
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.
Here is an example of how this looks.
​
​
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.
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 in a data grid and can interact with individual submission.
Notice that the data displayed in the table above is overlaid on a 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 like 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.
Webform Submission PDF's
In addition to creating and uploading existing PDF documents, the Form.io platform can be used to create PDF’s of normal webform submissions. To achieve this, first create a new webform by clicking on the Forms section and then click on Create Form and then API Webform
Once you are here, create a new Webform with several sections using the Panel component, like this.
Once, the form is created, you can now create a new submission by clicking on Use button and then fill out the form you just created.
Once you fill out the form and create a new submission, you will be redirected to a submission view page, where you will then see a PDF icon to download the submission.
Clicking this icon will then create a submission as a PDF for download or print.
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 our example, lets edit the Team Information panel. In the seetings for this panel, we will then introduce a special class to that 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.
​
​
Custom PDF Viewer
By default, the submission PDF’s that are generated use a hosted Form viewer application to render the submissions. This is great for many use cases, but there may be other situations where you would like to introduce your own viewer application to render the submissions for PDF generation. This is very helpful if you wish to provide your own PDF templates, or maybe even create submission pdf’s that introduce your own custom elements into the pdf generation. To achieve this, the first thing you will need to do is fork the Form Viewer found @
​https://github.com/formio/formio-viewer​
Once you download this Viewer application, you will want to make sure you install dependencies with the following command.
1
npm install
Copied!
You can make any changes you would like to the application. For example, we could use the Paper Theme from Bootswatch by making the following change to the src/index.html
src/index.html
1
document.write('<link rel="stylesheet" href="lib/bootswatch/paper/bootstrap.min.css" />');
Copied!
You can now compile this application using the following command.
1
gulp build
Copied!
This will create a dist folder, which you can then launch to your own hosting service. Once you have this hosted, you can then edit your form settings, and then introduce a new Custom Property called viewer and then set the value to the URL of your custom viewer application like so.
Using a 'key - value' approach
Another way to configure the PDF viewer is by using a PDF Viewer URL field in the PDF Settings section.
Using 'PDF Viewer URL' field
Once you save, and then go back to a submission and download that submission, you will notice that the PDF download now uses your own custom viewer application to render the submission PDF.
If you wish to make all of your PDF’s generated by your deployed PDF server use this viewer, then you can simply set the Environment Variable FORMIO_VIEWER within your Docker container run command like the following.
1
docker run -itd \
2
  -e "FORMIO_SERVER=https://formio.yourdomain.com" \
3
  -e "FORMIO_PROJECT=59b7b78367d7fa2312a57979" \
4
  -e "FORMIO_PROJECT_TOKEN=wi83DYHAieyt1MYRsTYA289MR9UIjM" \
5
  -e "FORMIO_PDF_PROJECT=https://formio.yourdomain.com/yourproject" \
6
  -e "FORMIO_PDF_APIKEY=is8w9ZRiW8I2TEioY39SJVWeIsO925" \
7
  -e "FORMIO_VIEWER=https://formio.github.io/formio-viewer/dist?theme=paper" \
8
  -e "FORMIO_S3_KEY=[S3 KEY]" \
9
  -e "FORMIO_S3_SECRET=[S3 SECRET]" \
10
  -e "FORMIO_S3_BUCKET=[S3 BUCKET]" \
11
  -e "FORMIO_S3_REGION=[S3 REGION]" \
12
  --restart unless-stopped \
13
  --name formio-files-core \
14
  -p 80:4005 \
15
  formio/formio-files-core;
Copied!
Please view the documentation @ https://help.form.io/userguide/pdfserver/#pdf-server-environment-variables for more information.
Hosted Viewer
The current viewer is currently hosted @ https://formio.github.io/formio-viewer/dist. If you wish to make changes to the theme based on Bootswatch Themes, then you can use the following format
1
https://formio.github.io/formio-viewer/dist?theme=paper
Copied!
Like so…
You can also change the theme using the PDF Theme select in the PDF Settings section
Viewer Parameters
There are also some parameters that you can pass to the Hosted viewer if you wish 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.
1
https://formio.github.io/formio-viewer/dist?theme=paper&header=0
Copied!
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 Parmameters
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, if you wish to alter the margins of the generated PDF document, you can provide the following to the PDF generation url.
1
https://yourproject.form.io/yourform/submission/[SUBMISSION_ID]/download?token=TOKEN&margin=20,20,20,20
Copied!
The accepted PDF parameters are as follows.
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