Visual Forms
Visual Forms allow you to embed a PDF form filling interface directly on your website. Unlike signature requests, visual forms do not include compliance features like audit trails or authentication tracking - they’re simply a visual component for filling out PDF templates.
How Visual Forms Work
Section titled “How Visual Forms Work”- Share a link to the visual form page for a template:
/templates/<template_id>/form?mode=visual, or set the template’s Online Form setting to show the visual form (or both forms, in tabs) at/templates/<template_id>/form - Users fill out the form with a visual interface that matches your PDF
- PDF is generated and available for download
Key Features
Section titled “Key Features”- Real-time preview of the PDF as users fill it out
- Field validation and formatting
- Support for all DocSpring field types
- Conditional logic: show, hide, or require fields based on other fields
- Mobile-responsive design
- No user accounts needed
- Perfect for internal forms or non-legal documents
Template Configuration
Section titled “Template Configuration”Visual forms work with any PDF template. Key settings to consider:
Online Form Privacy
Section titled “Online Form Privacy”Set “Online Form Privacy” to Public so that users who aren’t signed in to DocSpring can open the hosted or embedded visual form.
Submission Privacy
Section titled “Submission Privacy”- Public: PDFs can be downloaded immediately after generation
- Private: Requires authentication to download the generated PDF
Private Submissions and API Tokens
Section titled “Private Submissions and API Tokens”Never put an API token in a page. Anyone who opens the page can read it and use it to call the API as your account: read every submission, change templates, and generate PDFs that use your credits.
Visual Forms JS used to accept apiTokenId and apiTokenSecret options, so the form could download a private
submission’s PDF. Pages that pass them keep working, but from version 2.19.0 the form logs a warning in the browser
console. If your page passes them, remove them, then create a new API token and revoke the old one on the
API Tokens page: the old token’s secret has been public.
To get the PDF of a private submission, use your server:
- In the page, send the submission ID that
onSavegives you to your server. - On your server, get the submission with your API
token, check that its
template_idis your template, and download the PDF fromfiles.pdfonce it’s processed. Or use thesubmission.processedwebhook, which needs no submission ID from the page.
When the data comes from your server, or the person needs to sign, use a signature request instead. Your server creates it with your API token, and the page gets an authentication token that opens only that signature request.
Redirect URL
Section titled “Redirect URL”Configure where users go after form submission:
- Set in template settings as default
- Override with the
redirectURLoption when embedding the form
After its ? or #, the URL can have variables such as
?name={{ data.first_name }}, which the form fills in with what the person submitted.
Show Continue Once Required Fields Are Filled In
Section titled “Show Continue Once Required Fields Are Filled In”The form header has a Next button that takes the user through each field in turn. By default, while the user is in
a field, the Continue button only replaces it once every field has a value or has been visited. To let users skip
the optional fields, check
Show Continue Once Required Fields Are Filled In in the template’s settings. Continue then appears as soon as
every required field is filled in. You can also set it with the allowSkippingOptionalFields option when embedding
the form, which overrides the template setting either way. Embedded visual forms use the setting and the option with
Visual Forms JS version 2.16.0 or above.
Required Field Color
Section titled “Required Field Color”Visual forms and signature requests highlight every field the user can fill in with the same translucent blue, and mark required fields with an asterisk. To make required fields stand out, open the template’s settings in the template editor and pick a Required field color on the Field defaults tab. Required fields are then highlighted in that color instead, including fields that conditional logic makes required.
- The highlight stays see-through, so the PDF is still visible underneath.
- It never appears in the generated PDF.
- A field with a background color keeps that color, and a field with an error is still shown in red. This includes the template’s default Background Color: when it’s set, text fields show it instead of the required field color.
- To use the color for new templates, set Required Field Color under Visual Form Defaults on your account’s Template defaults page. Use Update Templates on that page to apply it to existing templates.
Embedded visual forms show it with Visual Forms JS version 2.16.0 or above.
Clearing Optional Fields
Section titled “Clearing Optional Fields”While someone is in a field, it keeps showing its value (its default value, defaultFormData value or formula result),
and they edit it as in any form. They can clear an optional field, or uncheck the selected option of an optional radio
button group, and it’s left empty in the PDF. A required field that someone clears gets its default value back when they leave it.
A text, number, email or URL field that someone has changed shows a ↺ button while it’s focused or the mouse is over
it. The button puts back what the field showed before they changed it: its default value, its defaultFormData value,
its value from the submission, or what its formula calculates now. Tab moves from
the field to the button, and Enter presses it.
Accounts that use template JSON schema version 1 can’t submit an empty number, or an empty value for a field with a
list of options. When one of those fields has a default value, a defaultFormData value or a value from the
submission, clearing it brings that value back, and the form submits it. To let people clear these fields, upgrade
your template schema in your account settings. You can revert the upgrade at
any time.
Keyboard
Section titled “Keyboard”Visual forms and signature requests can be filled in without a mouse:
- Tab moves to the next field and Shift+Tab to the previous one, selecting the field’s text so that typing replaces it. A group of radio buttons counts as one field.
- The arrow keys move between the options of a radio button group and select them.
- Space checks or unchecks a checkbox, and selects the focused radio button (or clears it, if the field is optional and that option is already selected).
- Escape leaves the current field.
On a page with an inline form, these keys go to the form while the user is in it: after they click a field, or while nothing else on the page is focused. Once they click or focus something else on your page, your page gets its own keyboard behavior back until they click the form again. Embedded visual forms support Shift+Tab and the arrow keys from Visual Forms JS version 2.16.0.