## Overview

The Document Gallery widget provides a gallery for displaying PDF documents and web graphic files of a page. It transforms document attachments into a visual browsing experience, automatically collecting all viewable documents from a page, organizing them into a slideshow format, and providing intuitive navigation through thumbnails or direct clicking. Rather than displaying documents as a simple list, it presents them in a full-featured gallery/carousel interface powered by the Fotorama library.

The widget handles multiple media types seamlessly:
- **Images** (JPG, JPEG, BMP, GIF, TIFF, SVG, PNG) display directly
- **Documents** (PDF, ODP presentations) render via an embedded viewer (ViewerJS)
- **Videos** (MP4, MOV) play with native HTML5 controls

## Use Cases

### Project Photo Documentation
When a project page has multiple photos documenting progress, milestones, or deliverables, this widget allows stakeholders to browse through all images in a polished gallery format rather than viewing them individually.

### Product/Asset Image Showcase
For pages representing products, assets, or inventory items that have multiple associated images, this widget enables users to see all product views in an engaging slideshow format.

### Presentation Viewing
When ODP or PDF presentations are attached to a page, users can view them directly within the widget without downloading, making it easy to share slide decks or reports.

### Video Collection Display
For pages with attached video content (MP4, MOV), the widget provides an integrated video player experience, useful for training materials, recorded meetings, or media assets.

### Document Hub Pages
A page can be configured to display documents from another page (via the BASEPAGE configuration), allowing creation of document "hub" views that aggregate content from different sources.

## Design Considerations

### When to Use This Pattern
- When documents are primarily visual (images, presentations, videos)
- When users need to browse through multiple related documents
- When a polished, magazine-style presentation is desired
- When documents should be viewable without downloading

### Display Configuration
The widget offers flexible sizing options:
- **Height**: Set a fixed pixel height (default: 600px)
- **Ratio**: Override height with an aspect ratio (e.g., "4/3") for responsive layouts
- **Width**: Always 100% of the container width

### Navigation Options
- **"When required"** (default): Shows thumbnail navigation when multiple documents exist
- **"Never"**: Hides navigation completely; users navigate by clicking or swiping

### Source Flexibility
By default, the widget displays documents from the current page. Optionally, configure the "Page" (basePage) parameter to reference documents from a different page, useful for creating document hubs or aggregated views.

## Related Patterns

### Alternative Widgets
- **cf.cplace.pdfPreview** - Specialized for PDF preview only, without carousel features
- **cf.cplace.dragAndDropImageView** - Image-focused widget with drag-and-drop positioning capabilities

### When to Choose Document Gallery
Choose this widget when you need a unified gallery experience for multiple media types. For single-document PDF viewing, cf.cplace.pdfPreview may be more appropriate. For advanced image positioning needs, cf.cplace.dragAndDropImageView offers more control.