Signature Widget Documentation

Overview​

The Signature widget allows users to capture digital signatures directly within forms using an interactive canvas. Users can draw their signature using mouse, touch, or stylus input, and the signature is automatically saved as image data when complete.

Features​

• Interactive Canvas: Draw signatures using mouse, touch, or stylus
• Real-time Capture: Signatures are automatically saved as the user draws
• Clear Function: Built-in clear button to reset the signature
• Responsive Design: Canvas automatically resizes based on device pixel ratio
• Form Integration: Seamlessly integrates with form validation
• Accessibility: Supports keyboard navigation and screen readers

Configuration Options​

Global Settings​

Basic Configuration​

Name

• Description: Display label for the signature field
• Type: Text input
• Required: Yes
• Example: "Customer Signature", "Authorization Signature"

Variable/Model

• Description: Variable name to store the signature data
• Type: Text input
• Required: Yes
• Format: Valid JavaScript variable name
• Example: customer_signature, approval_sign
• Note: The signature is stored as a base64-encoded data URL

Validation Settings​

Configure visibility, requirement, and accessibility across different screens/contexts.

Screen-based Validation​

Configuration Options:

• Available: Controls if the widget appears on specific screens
• Visible: Shows/hides the widget based on conditions
• Required: Makes signature mandatory for form submission
• Disable: Prevents user interaction (signature becomes read-only)

Advanced Validation Conditions​

Use JavaScript expressions with dynamic variables:

Example Conditions:

// Show only if user role is manager
{{user.role}} === 'manager'

// Required only for high-value transactions
{{transaction.amount}} > 10000

// Disable after approval
{{status}} === 'approved'

Style Configuration​

Canvas Dimensions​

Width

• Description: Canvas width
• Type: Text input
• Default: 100% (responsive)
• Format: CSS units (px, %, em, rem)
• Example: "400px", "100%", "20rem"

Height

• Description: Canvas height
• Type: Text input
• Default: Auto-calculated
• Format: CSS units (px, %, em, rem)
• Example: "200px", "15vh"

Styling Options​

Class Names

• Description: Custom CSS classes for styling
• Type: Text input
• Format: Space-separated class names
• Example: "signature-large bordered-canvas"

Dynamic Classes

• Description: Conditional CSS classes based on form state
• Type: JavaScript expression
• Example:

{
  'signature-required': {{isRequired}},
  'signature-error': {{hasError}},
  'signature-completed': {{signature}} !== undefined
}

Validation Rules​

Built-in Validation​

Required Field Validation

• Automatically validates if signature is present when required
• Shows customizable error message
• Integrates with form submission validation

Custom Validation Rules

Add additional validation rules beyond the basic required field:

// Custom rule examples
{
  validator: (value) => {
    return value && value.length > 1000; // Minimum signature complexity
  },
  message: "Please provide a more detailed signature"
}

Usage Examples​

Basic Implementation​

<!-- Minimal signature widget -->
<signature-widget 
  name="Customer Signature"
  model="customer_signature"
  required="true">
</signature-widget>

Advanced Configuration​

<!-- Full-featured signature widget -->
<signature-widget 
  name="Authorization Signature"
  model="auth_signature"
  required="true"
  width="500px"
  height="250px"
  class="signature-field bordered"
  validation-message="Signature is required for authorization">
</signature-widget>

Conditional Signature​

// Show signature field only for specific conditions
{
  visible: "{{user.role}} === 'approver' && {{amount}} > 5000",
  required: "{{document.type}} === 'contract'"
}

Technical Implementation​

Data Storage​

Format: Base64-encoded data URL Example:

data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mP8/5+hHgAHggJ/PchI7wAAAABJRU5ErkJggg==

Canvas Technology​

• Library: SignaturePad
• Rendering: HTML5 Canvas
• High DPI Support: Automatic pixel ratio detection
• Event Handling: Mouse, touch, and stylus input

Browser Compatibility​

• Modern Browsers: Full support (Chrome, Firefox, Safari, Edge)
• Mobile Devices: Native touch support
• Tablet Devices: Stylus and touch support
• Accessibility: Screen reader compatible

Integration Examples​

Form Submission​

// Access signature data in form submission
function submitForm() {
  const signatureData = this.models.customer_signature;
  
  if (signatureData) {
    // Signature is available as base64 data URL
    console.log('Signature captured:', signatureData);
  }
}

Validation Check​

// Custom validation logic
function validateSignature() {
  const signature = this.models.customer_signature;
  
  if (!signature) {
    return { valid: false, message: 'Signature is required' };
  }
  
  return { valid: true };
}

Clear Signature Programmatically​

// Clear signature from code
function clearSignature() {
  this.models.customer_signature = undefined;
}

Best Practices​

User Experience​

1. Clear Instructions: Provide clear labeling and instructions
2. Appropriate Size: Ensure canvas is large enough for comfortable signing
3. Error Handling: Show clear error messages for validation failures
4. Responsive Design: Test on various devices and screen sizes

Security Considerations​

1. Data Validation: Validate signature data on server-side
2. File Size: Monitor signature file sizes for performance
3. Storage: Implement appropriate data retention policies
4. Privacy: Ensure compliance with data protection regulations

Performance Optimization​

1. Canvas Size: Balance quality with performance
2. Compression: Consider image compression for large signatures
3. Caching: Implement appropriate caching strategies
4. Loading: Show loading states during signature capture

Troubleshooting​

Common Issues​

Signature Not Saving

• Check model name configuration
• Verify form submission handling
• Ensure canvas is properly initialized

Canvas Not Responsive

• Verify width/height settings
• Check CSS conflicts
• Test on different devices

Validation Errors

• Review required field settings
• Check validation rules syntax
• Verify screen-specific configurations

Performance Issues

• Reduce canvas dimensions if needed
• Optimize image compression
• Check for memory leaks in signature handling

Debug Information​

// Debug signature widget state
console.log('Signature Model:', this.models.customer_signature);
console.log('Widget Visible:', this.visible);
console.log('Widget Required:', this.required);
console.log('Widget Disabled:', this.disable);

API Reference​

Events​

• endStroke: Triggered when user completes a stroke
• beforeClear: Triggered before signature is cleared
• afterClear: Triggered after signature is cleared

Methods​

• clear(): Clears the signature canvas
• fromDataURL(): Loads signature from data URL
• toDataURL(): Exports signature as data URL
• on(): Enables signature input
• off(): Disables signature input

Properties​

• signaturePad: Reference to SignaturePad instance
• canvas: Reference to canvas element
• data: Current signature data URL
• isDisable: Current disabled state