## Overview

The PDF Preview widget enables you to embed a PDF and shows the first page of the document directly within a cplace page. It provides an inline preview of PDF files that are referenced via Document reference attributes, allowing users to view PDF content without opening or downloading the file. The widget uses PDF.js library to render PDFs in an HTML5 canvas with automatic scaling and optional download functionality.

## Use Cases

### When to Use This Widget

- **Document Preview on Pages**: Display PDF attachments or referenced documents directly on entity pages without requiring users to download or open them separately
- **Quick Visual Reference**: Provide a quick visual preview of PDF documents (e.g., contracts, reports, diagrams) on dashboards or detail pages
- **Document Galleries**: Show preview thumbnails of multiple PDF documents in a collection
- **Form Attachments**: Display PDF forms or documentation alongside data entry forms
- **Report Previews**: Show generated PDF reports inline on summary pages

Use this widget when:
- You want to provide immediate visual context of a PDF document
- The first page of a PDF contains the most relevant information (e.g., cover pages, summary sheets)
- You want to reduce friction by avoiding the need to download files just to see their content
- You're building document management interfaces where quick previews enhance usability

### When NOT to Use This Widget

- **Multi-page PDFs**: When users need to view or interact with multiple pages of a PDF (only the first page is displayed)
- **Non-PDF Documents**: When the referenced attribute points to non-PDF documents (the widget only works with PDF files)
- **Non-Document References**: When the referenced document is not a Document entity type
- **Interactive PDFs**: When users need to interact with PDF form fields or annotations

## Design Considerations

### Key Features

- **Inline PDF Rendering**: Displays the first page of a PDF file directly in the widget using HTML5 canvas
- **Dynamic Scaling**: Automatically scales the PDF to fit the widget width or height (depending on configuration)
- **Access Control**: Respects cplace's permission system and displays appropriate messages for insufficient rights
- **Optional Download Button**: Configurable download button for accessing the full PDF
- **Widget Reload**: Supports dynamic reload to refresh the PDF preview
- **Error Handling**: Provides user-friendly error messages for various failure scenarios

### Rendering Behavior

The widget offers two scaling modes:
- **Width-based scaling** (default): When no fixed height is set, the PDF scales to fit the widget width and the widget height adjusts based on the PDF's aspect ratio
- **Height-based scaling**: When a fixed height is configured, the PDF scales to fit the specified height

### Prerequisites and Dependencies

**System Requirements**:
- PDF.js library must be available in the frontend
- Document entity type must be available (platform feature)
- Modern browser with HTML5 canvas support

**Configuration Prerequisites**:
- Entity type must have at least one reference attribute pointing to Document entities
- The attribute must have multiplicity of 1..1 or 0..1
- Users must have read access to referenced documents

### Limitations

1. **Single Page Only**: Only displays the first page of the PDF
2. **PDF Files Only**: Does not work with other document types (Word, Excel, images, etc.)
3. **No Interactivity**: Cannot interact with PDF form fields or annotations
4. **No Navigation**: Cannot scroll or navigate to other pages
5. **Canvas Rendering**: Some PDF features may not render perfectly (complex fonts, advanced graphics)

## Related Widgets

### Alternative Widgets

- **Files Widget** (`cf.platform.files`): Shows all attached files, but doesn't provide inline preview
- **Dynamic Iframe Widget** (`cf.cplace.platform.dynamicIframe`): Can embed external content, but doesn't handle PDF rendering directly
- **Image Gallery Widget** (`msg.scripts.imagegallery.basic`): Shows image previews but focused on images rather than PDFs

### Integration Context

- Works with any custom entity type that has Document reference attributes
- Integrates with cplace's permission system for access control
- Compatible with cplace's widget framework (reload actions, fixed heights, frames)
- Can be used on any page layout that supports widgets
- Complements document management capabilities in cplace