Embedded Visual Forms

This guide walks through implementing visual forms for PDF generation without the compliance features of data requests. For conceptual documentation about visual forms, see the Visual Forms documentation.

Implementation Steps

1. Prepare Your Template

First, ensure your PDF template is configured for visual forms:

1. Upload your PDF to DocSpring
2. Add form fields using the Template Editor
3. Configure template settings:
   • Set submission privacy (Public recommended)
   • Configure redirect URL (optional)
   • Set up field defaults and validation

Template Editor Guide Learn how to create and configure PDF templates

2. Include the JavaScript Library

Add the visual forms library to your webpage:

Include visual forms library

<script
  type="text/javascript"
  src="https://cdn.docspring.com/embed/visual_form.v2.7.1.js"
></script>

3. Initialize the Form

Create a visual form with your template ID:

Basic initialization

<script>
  DocSpring.createVisualForm({
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>

This opens the form as a modal overlay. For inline embedding:

Inline form

<div id="form-container"></div>

<script>
  DocSpring.createVisualForm('#form-container', {
    templateId: 'YOUR_TEMPLATE_ID'
  })
</script>

4. Pre-fill Form Data (Optional)

You can pre-populate form fields with default or static data:

Pre-filled form data

DocSpring.createVisualForm({
  templateId: 'YOUR_TEMPLATE_ID',

  // Default values (user can modify)
  defaultFormData: {
    customer: {
      name: 'John Smith',
      email: '[email protected]'
    },
    date: '2024-01-15'
  },

  // Static values (user cannot modify)
  staticFormData: {
    company_name: 'Acme Corporation',
    invoice_number: 'INV-2024-001'
  }

})

Note

Form data must match your template’s JSON schema structure. Use nested objects for grouped fields.

5. Handle Form Events

Add callbacks to respond to form events:

Event callbacks

DocSpring.createVisualForm({
  templateId: 'YOUR_TEMPLATE_ID',

  // Form is ready
  onLoad: function() {
    console.log('Form loaded');
  },

  // Field interactions
  onFieldChange: function(field) {
    console.log('Field changed:', field.name, field.value);
  },

  // Form submission
  onSubmit: function(formData) {
    console.log('Form submitted:', formData);
    // Send data to your server if needed
  },

  // PDF generation
  onProcessed: function(data) {
    console.log('PDF ready:', data.downloadURL);
    // Custom handling (analytics, notifications, etc.)
  },

  // Error handling
  onError: function(error) {
    console.error('Form error:', error);
    alert('There was an error processing your form.');
  }

})

6. Customize the Experience

Visual forms offer extensive customization options:

Customization options

DocSpring.createVisualForm({
  templateId: 'YOUR_TEMPLATE_ID',

  // UI Options
  focusFirstFieldOnLoad: true,
  showSignatureModalOnFocus: true,
  downloadButtonLabel: 'Get My Document',

  // Skip terms of service
  skipAgreeToTermsOfService: true,

  // Custom messages
  pdfProcessingTitle: 'Creating Your Document...',
  completedTitle: function(template) {
    return 'Your ' + template.name + ' is Ready!';
  },

  // Redirect after completion
  redirectURL: 'https://yoursite.com/thank-you',
  waitForPDF: false  // Redirect immediately

})

7. Style the Form (Optional)

Apply custom CSS to match your brand:

Custom styling

.dsp-form {
  font-family: 'Your Font', sans-serif;
}

.dsp-button.dsp-primary {
background-color: #your-brand-color;
border-color: #your-brand-color;
}

.dsp-header {
background-color: #f8f9fa;
border-bottom: 1px solid #dee2e6;
}

.dsp-field.focused {
box-shadow: 0 0 0 3px rgba(your-color, 0.1);
}

8. Handle Field Overrides (Advanced)

Dynamically modify field properties:

Field overrides

DocSpring.createVisualForm({
  templateId: 'YOUR_TEMPLATE_ID',

  fieldOverrides: {
    // Hide sensitive fields
    ssn: { hidden: true },

    // Change field styling
    signature: {
      backgroundColor: 'FFFEF0',
      borderColor: '2E7D32'
    },

    // Make fields required
    email: { required: true }
  }

})

Production Deployment

Domain Verification

DocSpring verifies that forms are loaded from authorized domains. Add your domain in the template settings.

Caution

Remember to remove domainVerification: false before deploying to production.

Troubleshooting

Common Issues

Form doesn’t load

• Check template ID is correct
• Verify domain is authorized
• Check browser console for errors

Fields don’t appear

• Verify template has form fields and has been saved successfully
• Check if fields are hidden by overrides
• Make sure you are using the right template version - you may need to publish a new version.

PDF doesn’t generate

• Check API logs for validation errors

Debug Mode

Enable debugging for detailed console logs:

Enable debug logging

DocSpring.DEBUG = true;
DocSpring.createVisualForm({
  templateId: 'YOUR_TEMPLATE_ID'
})

Next Steps

Visual Forms JavaScript API Reference Complete API reference with all options and callbacks

Visual Forms Documentation Learn about visual forms and how they work

Data Requests Guide When you need legally binding signatures with compliance

Visual Forms Changelog Changelog entries for the Visual Forms JavaScript library