PDF Widget Documentation

Overview​

The PDF widget allows you to display PDF documents directly in your interface. It renders PDFs using an iframe and provides fallback handling for cases where the PDF cannot be loaded or no source is provided.

Configuration Options​

Global Configuration​

Basic Settings​

Name

• Field: Widget name identifier
• Usage: Set a descriptive name for easy identification in the interface
• Example: "Contract Document", "User Manual"

Variable/Model

• Field: Model binding for dynamic PDF sources
• Usage: Bind to a variable that contains the PDF URL
• Format: Variable name (e.g., documentUrl, pdfSource)
• Dynamic: Can be updated programmatically to change the displayed PDF

Default Value

• Field: Static PDF source URL
• Usage: Set a default PDF to display when no dynamic source is provided
• Format: Complete URL to PDF file
• Examples:
  • https://example.com/documents/manual.pdf
  • https://storage.googleapis.com/bucket/document.pdf
  • /assets/files/sample.pdf

Content Behavior​

The widget follows this priority order for PDF sources:

1. Dynamic Model Value: If a model is bound and has a value, it takes precedence
2. Static Default Value: Used when no model value is available
3. Placeholder: Shows "No PDF to read" message when neither source is available

Validation Configuration​

Screen-Based Visibility​

Configure widget behavior across different screen sizes and contexts:

Available

• Purpose: Controls whether the widget appears in the interface
• Options: Toggle on/off per screen type
• Use Case: Hide PDF viewer on mobile devices for better performance

Visible

• Purpose: Dynamic visibility based on conditions
• Options:
  • Boolean toggle for simple show/hide
  • Advanced conditions using JavaScript expressions
• Examples:
  • {{user.role}} === 'admin' - Only show for admin users
  • {{documentType}} === 'contract' - Show only for contract documents

Required

• Purpose: Mark the PDF widget as mandatory for form validation
• Behavior: Typically used when PDF viewing is required before proceeding
• Note: More applicable when PDF widget is part of form workflows

Disable

• Purpose: Prevent interaction with the widget
• Use Case: Show PDF but prevent user interaction in certain states

Style Configuration​

Dimensions​

Width

• Field: Widget width in pixels or percentage
• Format: Number + unit
• Examples: 800px, 100%, 50vw
• Default: 100% (full container width)

Height

• Field: Widget height in pixels or percentage
• Format: Number + unit
• Examples: 600px, 80vh, 400px
• Default: 100% (full container height)

CSS Styling​

Class Names

• Field: Custom CSS classes for styling
• Format: Space-separated class names
• Examples: pdf-viewer, document-container bordered
• Usage: Apply custom styling or integrate with design systems

Dynamic Classes

• Purpose: Conditionally apply CSS classes based on data
• Format: JavaScript expressions returning class names
• Example: {{status === 'approved' ? 'approved-document' : 'pending-document'}}

Advanced Configuration​

Error Handling​

The widget automatically handles common PDF loading errors:

• 403 Forbidden: Shows placeholder when access is denied
• 404 Not Found: Displays placeholder for missing files
• Invalid URLs: Gracefully falls back to placeholder
• Network Issues: Provides user-friendly error state

Loading States​

Initial Load

• Shows iframe immediately when source is available
• Displays placeholder while determining content availability

Error Recovery

• Automatically retries loading when source changes
• Provides visual feedback for loading failures

Implementation Examples​

Basic Static PDF​

// Widget Configuration
{
  type: "pdf",
  options: {
    source: "https://example.com/documents/user-guide.pdf",
    width: "800px",
    height: "600px"
  }
}

Dynamic PDF with Model Binding​

// Widget Configuration
{
  type: "pdf",
  model: "selectedDocument",
  options: {
    source: "https://example.com/default.pdf", // fallback
    width: "100%",
    height: "500px"
  }
}

// Runtime Usage
// Update the PDF source dynamically
this.selectedDocument = "https://example.com/new-document.pdf";

Conditional PDF Display​

// Widget Configuration
{
  type: "pdf",
  model: "contractPdf",
  options: {
    validation: {
      mobile: {
        visible: false // Hide on mobile
      },
      desktop: {
        visible: "{{user.hasAccess}}" // Show based on user permissions
      }
    }
  }
}

Use Cases​

Document Viewer​

• Display contracts, manuals, or reports
• Provide in-app document review capabilities
• Eliminate need for external PDF applications

Form Integration​

• Show terms and conditions during registration
• Display reference documents alongside form fields
• Preview generated documents before submission

Content Management​

• Browse document libraries
• Preview files before download
• Display documentation with contextual relevance

Educational Content​

• Show lesson materials or worksheets
• Display reference guides and tutorials
• Provide interactive learning resources

Best Practices​

Performance Optimization​

1. Use appropriate dimensions: Don't make PDFs unnecessarily large
2. Implement lazy loading: Use visibility conditions to load PDFs only when needed
3. Optimize PDF files: Ensure source PDFs are web-optimized
4. Consider mobile experience: PDFs may not display well on small screens

User Experience​

1. Provide loading indicators: Users should know when content is loading
2. Handle errors gracefully: Show meaningful messages for failed loads
3. Ensure accessibility: Consider users who may need alternative document formats
4. Test across browsers: PDF rendering may vary between browsers

Security Considerations​

1. Validate PDF sources: Ensure URLs point to legitimate PDF files
2. Use HTTPS: Secure connections for PDF content
3. Access control: Implement proper authentication for sensitive documents
4. Content validation: Verify PDF content is appropriate and safe

Troubleshooting​

Common Issues​

PDF not displaying

• Verify the source URL is accessible
• Check for CORS restrictions on the PDF server
• Ensure the file is a valid PDF format

Layout problems

• Adjust width and height settings
• Check parent container CSS constraints
• Test responsive behavior across screen sizes

Performance issues

• Optimize PDF file sizes
• Implement conditional loading
• Consider pagination for large documents

Browser compatibility

• Test PDF rendering across different browsers
• Provide fallback options for unsupported browsers
• Consider using PDF.js for consistent rendering

Browser Support​

The PDF widget relies on browser native PDF support or plugins:

• Chrome/Edge: Native PDF viewer
• Firefox: Built-in PDF.js renderer
• Safari: Native PDF support
• Mobile browsers: May require external PDF apps

For guaranteed cross-browser compatibility, consider implementing PDF.js as a fallback renderer.