## Overview

Shows a preview of a Presentation Graphic export of visualized schedules.

The widget displays a preview of Presentation Graphic (PG) exports for project schedules. "PG" stands for "Presentation Graphic" and refers to a visual representation of project schedules (Gantt charts) that can be exported to PowerPoint (PPTX) or PDF formats. The widget generates paginated image previews of how schedules will appear in the final export and provides action buttons for configuration, refresh, and export operations.

## Use Cases

### Schedule Export Preview
Users want to see how their project schedules will look before exporting them to presentations.

**Example Scenario**: A project manager preparing a stakeholder presentation wants to preview how their project Gantt chart will appear in PowerPoint before generating the final export.

### Direct Schedule Export
Users need to quickly export project schedules to PowerPoint or PDF for reporting or presentations.

**Example Scenario**: During a project review meeting, a team lead needs to quickly export the current project schedule as a PDF to share with attendees.

### Connected Table Integration
Users want the preview to automatically update based on schedule selections in a connected table widget.

**Example Scenario**: A portfolio manager has a table listing multiple project schedules and wants to preview different schedules by clicking on rows in the table, with the PG preview automatically updating.

### Iterative Configuration
Users need to refine the visual presentation of schedules by iterating between configuration changes and preview.

**Example Scenario**: A project administrator is setting up a presentation profile with custom colors, column widths, and layout options, using the preview to validate each change.

## Design Considerations

### Schedule Selection Strategy

The widget supports multiple approaches to selecting schedules for preview and export:

- **Explicit Selection**: Directly select one or more schedule pages
- **Embedding Selection**: Use the schedule from the embedding page
- **Search-based Selection**: Use a search query to dynamically find schedules with optional sorting
- **Relative Selection**: Select schedules via an attribute on the embedding page
- **Connected Table**: Reactively select schedules from a connected table widget

Choose the selection strategy based on whether schedules are known at widget configuration time (explicit), determined by context (embedding/relative), or need to be dynamic (search/connected table).

### Profile Configuration

Profiles define how the presentation graphic is rendered (layout, colors, columns, etc.). The widget can:
- Use an explicitly selected profile page
- Use the profile configured in the first selected schedule
- Use a cplace.js script to dynamically determine the profile

Explicit profile selection is most predictable, while script-based selection allows for advanced customization based on context.

### Preview vs Export

The widget supports two primary operating modes:
- **Preview Mode**: Shows image preview of the presentation graphic with optional action buttons
- **Export Mode**: Hides the preview and only shows export buttons for direct downloads

Use preview mode when users need visual validation before export. Use export-only mode when space is limited or the visual preview is not needed.

### Display Options

Key visibility controls include:
- Toggle preview image visibility
- Control whether preview generates immediately on widget load
- Show/hide individual action buttons (refresh, edit, export PDF, export PPTX)
- Configure widget frame and title display
- Set fixed or dynamic widget height

These options allow tailoring the widget appearance for different use cases, from compact export-only buttons to full-featured preview interfaces.

## Related Widgets

### Related Types
- **Schedule Type**: Project schedules (Gantt charts) from the project planning plugin
- **Profile Type** (`cf.cplace.pptexport.profile`): Configuration pages that define PG layout and styling

### Integration Points
- **Table Widgets**: Can connect to any table widget to reactively update based on row selection, enabling master-detail patterns
- **PG Configurator**: Opens a separate configuration interface for designing the presentation layout
- **Export Handlers**: Backend handlers that generate PPTX and PDF exports

### Plugin Dependencies
- Part of the `cf.cplace.pptexport` plugin
- Works with schedules from `cf.cplace.projectPlanning`
- Uses the external library `cf-cplace-pgpptintegration` for PowerPoint generation

## Common Pitfalls

- **Invalid Configuration**: The widget cannot generate previews if both the button bar and preview are hidden, or if no schedules or profile are selected
- **Performance**: Generating previews for many large schedules can be slow; consider limiting schedule selection or using search filters
- **Profile Mismatch**: Using the schedule's own profile may produce unexpected results if schedules have different profiles configured
- **Connected Table**: When using connected table mode, ensure the table widget is properly configured to emit selection events