PDF Forms
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 receiving 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 PDFs 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.
The Form.io PDF Solution is a powerful tool with two options: PDF Server and PDF Server Plus. Please see the below description of each to see which aligns best with the requirements of the Application being built.
The Use Case: Starting with dynamic, JSON-driven, responsive webforms that users are filling out and submitting within an application, I want to print out a PDF of the web form submission.
The Use Case: Forms are required to be on a pixel-perfect PDF background with a dynamic JSON form overlay on top of the PDF.
PDF-First forms can also be presented to the user as responsive web forms, but enable the ability to print the Submission to the pixel-perfect PDF background.
Contact [email protected] for more information on the PDF Plus Server
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.
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.
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.
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.
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 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”)
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 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.
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 styles, the PDF Viewer also utilizes the Font Awesome 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 |  |
Use both the Font Awesome icon library and Pretty Checkbox CSS Styling to create customized Checkbox and Radio components
In 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.
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.
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.
At times, you may want to include a pre-existing PDF form into another form. Use the 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.
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.
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.
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.
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 @ 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
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.
https://formio.github.io/formio-viewer/dist?theme=paper
Like so…
You can also change the theme using the PDF Theme select in the PDF Settings section
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 |
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 |
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 @
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 from Bootswatch can be used by the Viewer by making the following change to the
src/index.htmlsrc/index.html
document.write('<link rel="stylesheet" href="lib/bootswatch/paper/bootstrap.min.css" />');
You can now compile this application using the following command.
gulp build
This will create a dist folder, which 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.
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 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 view the documentation @ https://help.form.io/userguide/pdfserver/#pdf-server-environment-variables for more information.
The PDF Form Settings allow the user to change various UI and theming elements for PDF First Forms and PDF submission downloads. Access Form Settings and scroll down to the PDF Settings section to utilize the following configurations.
Change the PDF dimensions by selecting a page size for the rendered PDF First Form. Read more on PDF Page Size
By default, the PDF's font size is determined by the vertical size of the PDF overlay field. Select a font size to globally set the field font size for the PDF First Form regardless of the field overlay size.
Set the Margin size of the rendered PDF First Form using the same margin guidelines for CSS attributes.
Hides the form title when viewing a Submission PDF download.
Check this if you would like to render the Submission PDF as plain text view. This setting will hide the field UI and only show the submitted text when viewing the download.
Check this if you would like your Submission PDF downloads to render with Condensed mode enabled. This setting will minimize field margins and padding as well as default the font size to 11pt. Field UI is replaced with an underline instead of the full box border.
Check this if you would like checkbox and radio components that are not checked or ticked to have background and borders when viewing the PDF First Form submission.
Activates the Submission Revision change log. PDF submission downloads will now display all Submission Revision information for the submission being viewed.
Apply your own templates to the PDF forms Header or Footer.
Inject HTML as a header for every page of the generated PDF. The Template should be valid HTML markup with the following classes used to inject printing values into them:
date- Formatted print datepageNumber- Current page numbertotalPages- Total amount of pages
Use
{{ formatDate( dateFormat, timezone ) }} with the moment-supported date format and timezone to customize the date displaying. Use Base64 for images.Last modified 12d ago