@cplace/mcp-server 1.3.14

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-outlookMessageIntegration-outlookMessages/research.md

@@ -0,0 +1,233 @@
+# Widget Research: cf.cplace.outlookMessageIntegration.outlookMessages
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.outlookMessageIntegration.outlookMessages`
+**Repository:** `cplace-paw`
+**Plugin:** `cf.cplace.outlookMessageIntegration`
+**Definition Class:** `OutlookMessagesWidgetDefinition.java`
+
+## Purpose
+
+The Outlook Messages widget enables users to import and display Microsoft Outlook email messages (.msg files) within cplace pages. Users can drag and drop Outlook message files directly into the widget, which parses the email data and creates structured email records as child pages, preserving the email content, metadata, and attachments.
+
+## Core Functionality
+
+### What This Widget Does
+
+The widget provides two main functions:
+
+1. **Email Import**: Accepts Outlook .msg files via drag-and-drop upload
+2. **Email Display**: Shows imported emails in a tabular format with key metadata
+
+When a user uploads an .msg file:
+- The widget parses the file using Apache POI's HSMF library (Microsoft Outlook MSG format parser)
+- Creates a new page of type "email" as a child of the current page
+- Extracts and stores email metadata (subject, sender, recipients, date)
+- Preserves the email body content (HTML or plain text)
+- Extracts and attaches any file attachments from the email
+- Displays the new email in the widget's table
+
+### Technical Architecture
+
+**Frontend Components:**
+- Template: `outlookMessagesWidgetDefinition.htm` - Drag-and-drop zone and table display
+- Controller: `OutlookMessagesWidgetCtrl.ts` - Upload handling and table refresh
+- Based on `AbstractUploadCtrl` for file upload functionality
+
+**Backend Components:**
+- `OutlookMessagesWidgetDefinition.java` - Widget definition and rendering
+- `MessageUploadHandler.java` - Processes uploaded .msg files and creates email pages
+- `OutlookMessagesTableHandler.java` - Generates updated table data after uploads
+- `OutlookMessagesWidgetState.java` - Manages widget state (upload URL, table reload URL)
+- `OutlookMessagesTableTemplateSubstitution.java` - Renders the email table
+
+**Data Model:**
+- Type: "email" (EMAIL type definition in OutlookMessageIntegrationAppTypes.java)
+- Attributes:
+  - `subject` (SingleString) - Email subject line
+  - `from` (SingleString) - Sender information
+  - `to` (MultiString) - Recipients list
+  - `date` (SingleDate) - Email timestamp
+  - `content` (SingleRichString) - Email body (HTML or plain text)
+  - `parent` (SinglePageReference) - Reference to parent page (hierarchical relationship)
+- All attributes are read-only after import
+- Attachments stored as Document entities linked to the email page
+
+## Use Cases
+
+### Primary Use Cases
+
+1. **Project Communication Archive**
+   - Teams working on projects can archive relevant email correspondence directly in project pages
+   - Keep all project-related information (tasks, documents, emails) in one place
+   - Preserve email context and history within the project workspace
+
+2. **Issue Documentation**
+   - When issues are reported or discussed via email, import the email into the issue page
+   - Create an audit trail of email communications related to specific issues
+   - Reference email content when resolving problems
+
+3. **Client Communication Tracking**
+   - Import customer or client emails into relevant customer/account pages
+   - Maintain a complete history of email interactions
+   - Share email context with team members who weren't on the original thread
+
+4. **Compliance and Record-Keeping**
+   - Store important business emails within structured records
+   - Create searchable archives of email communications
+   - Maintain email evidence linked to specific business processes or entities
+
+5. **Knowledge Management**
+   - Preserve valuable information shared via email
+   - Convert email discussions into searchable, structured content
+   - Make email knowledge accessible to broader teams
+
+### When to Use This Widget
+
+Choose this widget when:
+- The page represents an entity that may receive related email communications (projects, issues, customers, etc.)
+- You need to integrate email conversations into your cplace workflow
+- You want to preserve email context alongside other structured data
+- Team members need access to email information without forwarding or CC'ing
+
+### What Problem It Solves
+
+- **Information Silos**: Email conversations remain isolated in individual inboxes. This widget brings email content into the shared workspace.
+- **Context Loss**: Important email discussions are disconnected from related work items. The widget links emails directly to relevant pages.
+- **Manual Data Entry**: Instead of copying email content manually, users can import the entire message with metadata and attachments intact.
+- **Attachment Management**: Email attachments are preserved and accessible through cplace's document management.
+
+## Configuration Concepts
+
+### Widget Configuration
+
+The widget has minimal configuration as it provides a fixed functionality:
+
+1. **Embedding**:
+   - Can only be embedded in Page entities (or type definitions that apply to Pages)
+   - Enforced by `checkEmbeddableIn` method in the widget definition
+   - Creates hierarchical relationship: parent page → child email pages
+
+2. **Display Options**:
+   - No padding on widget container (`isNoPadding() = true`)
+   - Fixed table layout with columns: Subject, Attachments, Date, Recipient, Sender
+   - Emails sorted by date (most recent first)
+
+3. **Upload Handling**:
+   - Only accepts .msg file format (Microsoft Outlook Message format)
+   - Validates file extension before processing
+   - Shows upload progress indicator during file processing
+   - Displays error messages for invalid files or upload failures
+
+### User Interface Elements
+
+**Drag-and-Drop Zone:**
+- Visual drop zone with envelope icon
+- Upload progress indicator with percentage
+- Shows spinner during processing
+
+**Email Table:**
+- Displays all email pages that are children of the current page
+- Columns:
+  - Subject (clickable link to email page)
+  - Number of attachments (file icon with count)
+  - Date
+  - Recipients (To field)
+  - Sender (From field)
+- Automatically refreshes after successful upload
+
+### Technical Constraints
+
+- **File Format**: Only Microsoft Outlook .msg files are supported
+- **Parsing**: Uses Apache POI HSMF library for .msg file parsing
+- **Parent-Child Relationship**: Email pages are always created as children of the page containing the widget
+- **Read-Only Data**: Once imported, email data cannot be edited (enforces data integrity)
+- **Space Context**: Emails are created in the same space as their parent page
+
+## Context and Relationships
+
+### Related Components
+
+1. **Email Type Definition** (`OutlookMessageIntegrationAppTypes.EMAIL`)
+   - Defines the structure for imported email pages
+   - Includes default layout with content, attributes, and files widgets
+   - Uses "fa-envelope" icon for email pages
+
+2. **Document Management**
+   - Email attachments are created as Document entities
+   - Documents are linked to email pages via parent-child relationship
+   - Attachments preserve original filenames and content
+
+3. **Page Hierarchy**
+   - Emails use parent reference attribute for hierarchical structure
+   - Parent page can have multiple email children
+   - Email pages inherit space context from parent
+
+### Integration Points
+
+- **Upload Framework**: Extends `AbstractUploadCtrl` for consistent upload behavior across cplace
+- **Search System**: Emails are searchable like any other page type
+- **Attribute Display**: Email content can be displayed using standard cplace attribute widgets
+- **Files Widget**: Email attachments displayed via standard files widget on email detail page
+
+### Prerequisites
+
+- The page where the widget is embedded must allow child pages (hierarchical structure)
+- User must have edit permissions on the parent page to upload emails
+- Email pages are created in the same space as the parent (requires space permissions)
+
+### No Dependencies On
+
+- External Outlook/Exchange server connections (works with exported .msg files)
+- Active email accounts or IMAP/SMTP configuration
+- Email client plugins or integrations
+
+## Implementation Details
+
+### Email Parsing Process
+
+When a .msg file is uploaded:
+
+1. **Validation**:
+   - Check file extension is ".msg"
+   - Verify file can be read
+
+2. **Parse Email Metadata**:
+   - Extract subject (used as page title)
+   - Parse sender information (name and email address)
+   - Extract recipient list with names and email addresses
+   - Get message date/time
+
+3. **Process Email Body**:
+   - Attempt to extract HTML body first
+   - Fall back to plain text if HTML not available
+   - Convert line separators to `<br>` tags for plain text
+
+4. **Extract Attachments**:
+   - Iterate through attachment chunks in .msg file
+   - Create Document entity for each attachment
+   - Copy attachment data into document version
+   - Link documents to email page
+
+5. **Create Email Page**:
+   - Create page of type "email" with subject as title
+   - Set all metadata attributes
+   - Link to parent page
+   - Persist page and documents
+
+6. **Refresh Display**:
+   - Reload table via AJAX call
+   - Display updated list of emails
+   - Enable upload for next file
+
+### Error Handling
+
+- Invalid file format: Shows specific error message
+- Parse failures: Logged and generic error shown to user
+- Attachment extraction failures: Logged individually, continue processing other attachments
+- Upload progress tracking with visual feedback
+
+## Summary
+
+The Outlook Messages widget provides a streamlined way to integrate email communications into cplace's structured information management. By accepting Outlook .msg files via drag-and-drop, it eliminates the gap between email conversations and related work items, creating a unified view of all project-relevant information. The widget is particularly valuable for teams that need to maintain audit trails, preserve context, or share email information within collaborative workspaces.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-pageViewHeadline-widget/research.md

@@ -0,0 +1,217 @@
+# Widget Research: cf.cplace.pageViewHeadline.widget
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.pageViewHeadline.widget`
+**Widget Name:** Simple Headline
+**Repository:** cplace-paw
+**Plugin:** cf.cplace.pageViewHeadline
+
+## 1. Description
+
+The Simple Headline widget allows users to insert visually styled headlines with an optional subtitle on page views. It displays a title and optional subtitle with a large decorative icon in the background, customizable colors, and responsive design.
+
+## 2. Purpose and Functionality
+
+### Core Functionality
+The widget provides a visually prominent headline display that:
+- Shows a customizable title and optional subtitle
+- Displays the page's icon as a large, semi-transparent watermark in the background
+- Supports custom background and font colors
+- Renders without a frame or padding (seamless integration with page layout)
+- Adapts responsively to different screen sizes
+
+### Technical Implementation
+- **Definition Class:** `cf.cplace.pageViewHeadline.widget.PageViewHeadlineWidgetDefinition`
+- **Configuration Type:** `cf.cplace.pageViewHeadline.widgetConfiguration`
+- **Template:** HTML-based with inline style substitutions
+- **Styling:** LESS/CSS with responsive breakpoints
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Page Header Enhancement**
+   - Add visually appealing headers to important pages
+   - Create a professional, branded look for key content pages
+   - Differentiate page types through consistent headline styling
+
+2. **Visual Page Hierarchy**
+   - Make landing pages or section entry points stand out
+   - Provide clear visual distinction between different page types
+   - Guide users through content organization with visual cues
+
+3. **Branded Content Sections**
+   - Apply corporate colors to page headers
+   - Create consistent visual themes across page collections
+   - Support multi-language content with localized titles and subtitles
+
+4. **Dashboard and Overview Pages**
+   - Create attention-grabbing headers for dashboard pages
+   - Highlight summary or overview sections
+   - Provide context through both title and subtitle information
+
+### When to Use This Widget
+
+Choose the Simple Headline widget when:
+- You need a prominent, visually styled header for a page
+- Standard page titles are not prominent enough
+- You want to apply custom branding/colors to specific pages
+- You need both a main title and explanatory subtitle
+- You want to incorporate the page icon in a decorative way
+
+### When NOT to Use This Widget
+
+Avoid this widget when:
+- Simple page titles are sufficient
+- You need complex header functionality (interactive elements, buttons, etc.)
+- The page layout requires a standard frame or padding
+- You're working with non-page entities (widget only works on Page types)
+
+## 4. Configuration Options
+
+### Main Configuration Attributes
+
+1. **Localized Title** (required)
+   - Attribute: `LOCALIZED_TITLE`
+   - Type: LocalizedString
+   - Purpose: Main headline text, supports multiple languages
+   - Migrated from deprecated `widgetTitle` field
+
+2. **Localized Subtitle** (optional)
+   - Attribute: `LOCALIZED_SUBTITLE`
+   - Type: LocalizedString
+   - Purpose: Secondary text below the main title
+   - Migrated from deprecated `widgetSubTitle` field
+
+3. **Background Color** (optional)
+   - Attribute: `BACKGROUNDCOLOR`
+   - Type: Color (String)
+   - Purpose: Custom background color for the headline area
+   - Default: Gray if not specified
+
+4. **Font Color** (optional)
+   - Attribute: `FONTCOLOR`
+   - Type: Color (String)
+   - Purpose: Custom text color for title and subtitle
+   - Default: White with transparency if not specified
+
+### Visual Design Features
+
+- **Icon Display:** Automatically uses the embedding page's icon as a large watermark
+- **Icon Opacity:** 30% opacity (or 10% default) for subtle background effect
+- **Text Shadow:** Applied to both title and subtitle for readability
+- **Rounded Corners:** 3px border-radius for modern appearance
+- **Responsive Typography:**
+  - Desktop: Title 40px, Subtitle 24px, Icon 100px
+  - Tablet (≤767px): Title 30px, Subtitle 20px, Icon 70px
+  - Mobile (≤579px): Title 20px, Subtitle 14px, Icon 50px
+
+## 5. Context and Relationships
+
+### Entity Requirements
+- **Embeddable In:** Page entities only
+- **Embedding Type:** Widget (not embeddable as other types)
+- **Type Constraints:** Must be embedded in Page class or type definitions that apply to pages
+
+### Integration Points
+
+1. **Icon Service Integration**
+   - Retrieves icon from the embedding page entity
+   - Converts icon name to CSS class using IconService
+   - Displays as decorative background element
+
+2. **Localization Support**
+   - Full support for multi-language titles and subtitles
+   - Uses LocalizedString for content that adapts to user language
+   - Migrates legacy non-localized strings to localized format
+
+3. **Template System**
+   - Uses cplace's template substitution system
+   - HTML escaping for security
+   - Conditional rendering (subtitle optional)
+
+### Dependencies
+- **cf.cplace.platform:** Core platform functionality
+- **cf.cplace.dragAndDropImageView:** Plugin dependency
+
+## 6. Migration and Evolution
+
+### Historical Context
+- Originally used non-localized string attributes for title and subtitle
+- Migrated to LocalizedString attributes for better internationalization
+- Deprecated `TITLE` and `SUBTITLE` attributes maintained for backward compatibility
+- Live migration converts old configurations to new format
+
+### Migration Behavior
+The widget automatically migrates:
+- `widgetTitle` (deprecated) → `LOCALIZED_TITLE`
+- `widgetSubTitle` (deprecated) → `LOCALIZED_SUBTITLE`
+
+## 7. Example Configuration
+
+From the test setup, a typical configuration includes:
+
+```java
+{
+  "backgroundColor": "#652eff",
+  "fontColor": "#c9cdff",
+  "localizedTitle": {
+    "de": "Textseite (Einfache Überschrift, ohne Untertitel)",
+    "en": "Text Page (Simple Headline, without subtitle)"
+  }
+}
+```
+
+Or with subtitle:
+
+```java
+{
+  "backgroundColor": "#652eff",
+  "fontColor": "#c9cdff",
+  "localizedTitle": {
+    "de": "Fußzeile",
+    "en": "Footer"
+  },
+  "localizedSubtitle": {
+    "de": "Untertitel Text",
+    "en": "Subtitle text"
+  }
+}
+```
+
+## 8. Technical Characteristics
+
+### Rendering Behavior
+- **No Padding:** Widget sets `isNoPadding()` to true
+- **No Frame:** Widget sets `showFrame()` to false
+- **Seamless Integration:** Designed to blend with page layout without visible widget chrome
+
+### Responsive Design
+The widget includes three breakpoints:
+- **Desktop** (>767px): Full size, maximum visual impact
+- **Tablet** (≤767px): Medium size, balanced layout
+- **Mobile** (≤579px): Compact size, optimized for small screens
+
+### CSS Class Structure
+- `.cplace-page-view-alternative-headline`: Main container
+- `.icon`: Large decorative icon background
+- `h1`: Main title styling
+- `h2`: Subtitle styling (conditional)
+
+## 9. Summary
+
+The Simple Headline widget is a specialized formatting widget designed to create visually prominent, branded page headers in cplace. It combines a localized title and optional subtitle with customizable colors and the page's icon to create an eye-catching header that works across devices. The widget is particularly useful for landing pages, dashboards, and important content sections where standard page titles lack sufficient visual impact.
+
+**Key Strengths:**
+- Simple, focused purpose
+- Strong visual impact
+- Responsive design
+- Multi-language support
+- Easy customization
+
+**Limitations:**
+- Page-only embedding
+- Limited to static headline display
+- No interactive features
+- Fixed visual style (though colors are customizable)

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-pdfPreview-widget/research.md

@@ -0,0 +1,235 @@
+# PDF Preview Widget Research
+
+## Widget Information
+- **Widget ID**: `cf.cplace.pdfPreview.widget`
+- **Widget Name**: PDF Preview
+- **Repository**: `cplace-paw`
+- **Definition Class**: `cf.cplace.pdfPreview/src/main/java/cf/cplace/pdfPreview/script/PdfPreviewWidgetDefinition.java`
+
+## Purpose
+
+The PDF Preview widget displays the first page of a PDF 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.
+
+## Core Functionality
+
+### What It Does
+The widget renders the first page of a PDF document using PDF.js library within a canvas element on the page. It retrieves the PDF through a Document reference attribute and displays it inline with optional download functionality.
+
+### Key Features
+1. **Inline PDF Rendering**: Displays the first page of a PDF file directly in the widget using HTML5 canvas
+2. **Dynamic Scaling**: Automatically scales the PDF to fit the widget width or height (depending on configuration)
+3. **Access Control**: Respects cplace's permission system and displays appropriate messages for insufficient rights
+4. **Optional Download Button**: Configurable download button for accessing the full PDF
+5. **Widget Reload**: Supports dynamic reload to refresh the PDF preview
+6. **Error Handling**: Provides user-friendly error messages for various failure scenarios
+
+## Use Cases
+
+### Primary Use Cases
+1. **Document Preview on Pages**: Display PDF attachments or referenced documents directly on entity pages without requiring users to download or open them separately
+2. **Quick Visual Reference**: Provide a quick visual preview of PDF documents (e.g., contracts, reports, diagrams) on dashboards or detail pages
+3. **Document Galleries**: Show preview thumbnails of multiple PDF documents in a collection
+4. **Form Attachments**: Display PDF forms or documentation alongside data entry forms
+5. **Report Previews**: Show generated PDF reports inline on summary pages
+
+### When to Use This Widget
+- When you want to provide immediate visual context of a PDF document
+- When the first page of a PDF contains the most relevant information (e.g., cover pages, summary sheets)
+- When you want to reduce friction by avoiding the need to download files just to see their content
+- When building document management interfaces where quick previews enhance usability
+
+### When NOT to Use This Widget
+- When users need to view or interact with multiple pages of a PDF (only the first page is displayed)
+- When the referenced attribute points to non-PDF documents (the widget only works with PDF files)
+- When the referenced document is not a Document entity type
+
+## Configuration Options
+
+### Required Configuration
+| Configuration | Type | Description |
+|--------------|------|-------------|
+| **PDF Reference Attribute** | Reference Attribute | A single-value reference attribute that points to a Document entity containing a PDF file. Must be a reference constraint to the Document entity class. |
+
+### Optional Configuration
+| Configuration | Type | Default | Description |
+|--------------|------|---------|-------------|
+| **Show Download Button** | Boolean | `true` | Whether to display a download button below the PDF preview |
+| **Show Widget Frame** | Boolean | `true` | Whether to display the standard widget frame around the content |
+| **Height** | Number | Auto | Fixed height for the widget. When set, the PDF scales to fit the specified height. When not set, scales to fit the widget width. |
+
+### Configuration Details
+
+#### PDF Reference Attribute
+- Must be a reference attribute with multiplicity of exactly one (1..1) or at most one (0..1)
+- Must reference the Document entity type
+- The referenced document must be a PDF file (checked by file extension)
+- The enumeration provider (`PdfAttributeEnumerationProvider`) filters available attributes to only show those meeting these criteria
+
+#### Show Download Button
+- When enabled, displays a prominent download button below the PDF preview
+- Provides direct access to download the full PDF file
+- Uses the same URL as the preview, respecting access permissions
+
+#### Show Frame
+- Controls whether the standard cplace widget frame is displayed
+- When disabled, the widget content has no padding and appears borderless
+- Useful for creating seamless layouts or custom styling
+
+#### Height
+- When set, the widget has a fixed height and the PDF scales to fit vertically
+- When not set, the widget height adjusts dynamically based on the PDF's aspect ratio scaled to the container width
+- Supports dynamic resizing when the page layout changes
+
+## Technical Implementation
+
+### Backend Components
+
+#### Widget Definition (`PdfPreviewWidgetDefinition.java`)
+- Extends `WidgetDefinition` base class
+- Defines widget kind as `"cf.cplace.pdfPreview.widget"`
+- Uses `PdfPreviewWidgetState` to serialize widget state to JSON
+- Supports attribute name migration for type changes
+- Sets `isNoPadding()` to true for edge-to-edge rendering
+
+#### Widget State (`PdfPreviewWidgetState.java`)
+- Encapsulates runtime state:
+  - `pdfUrl`: Download URL for the PDF file
+  - `showDownloadButton`: Whether to show the download button
+  - `insufficientRights`: Boolean flag for access control
+  - `reloadStateUrl`: URL for dynamic widget reload
+- Performs security checks using `FunctionsHelper.getUrlAndCheckAccess()`
+- Validates that referenced entity is a Document with PDF extension
+- Handles null/missing references gracefully
+
+#### Widget Configuration Types (`PdfPreviewWidgetTypes.java`)
+- Defines configuration schema:
+  - `ATTRIBUTE`: Dynamic string enumeration for selecting the PDF reference attribute
+  - `SHOW_DOWNLOAD_BUTTON`: Boolean with default `true`
+  - `SHOW_FRAME`: Boolean with default `true`
+  - `HEIGHT`: Number attribute for fixed height
+- Uses `PdfAttributeEnumerationProvider` to populate attribute options
+
+#### Attribute Enumeration Provider (`PdfAttributeEnumerationProvider.java`)
+- Filters available attributes to show only valid PDF reference attributes
+- Requirements:
+  - Multiplicity: exactly one (1..1) or at most one (0..1)
+  - Type constraint: ReferenceConstraint
+  - Referenced entity class: Document
+- Ensures configuration only allows valid attribute selections
+
+### Frontend Components
+
+#### Angular Directive (`cfCplacePdfPreview.ts`)
+- Controller: `PdfPreviewCtrl`
+- Manages PDF loading, rendering, and lifecycle
+- Key responsibilities:
+  - PDF document loading via PDF.js (`pdfjsLib.getDocument()`)
+  - Canvas-based rendering of first page
+  - Dynamic scaling based on fixed height or width
+  - Widget resize handling with debouncing
+  - Error handling and user feedback
+  - Memory management (cleanup on destroy)
+
+#### Key Frontend Features
+1. **Dynamic Scaling**: Calculates viewport scale based on either:
+   - Fixed height: Scales to fit the specified height
+   - Dynamic height: Scales to fit the container width
+2. **Resize Handling**: Responds to widget resize events and redraws the PDF accordingly
+3. **Lazy Rendering**: Only loads and renders when needed, with caching of loaded pages
+4. **Error States**: Handles and displays:
+   - Insufficient rights
+   - PDF loading errors
+   - Missing/no file referenced
+5. **Reload Support**: Integrates with widget reload action to refresh content dynamically
+
+#### Template (`pdfPreviewWidgetDefinition.htm`)
+- Displays conditional content based on state:
+  - Info alert for insufficient rights
+  - Error alert for display failures
+  - Info alert for missing file reference
+  - Canvas container for PDF rendering
+  - Optional download button
+
+### Dependencies
+- **PDF.js**: JavaScript library for parsing and rendering PDF documents
+- **AngularJS**: Frontend framework for directive and controller
+- **cplace Widget Framework**: Integration with cplace's widget system
+- **Document Entity**: Requires the Document entity type from cplace platform
+
+## Related Widgets & Context
+
+### Similar 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
+- **Document Gallery Widget** (`msg.scripts.imagegallery.basic`): Shows image previews but focused on images rather than PDFs
+
+### Integration Points
+- 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
+
+### Part of Larger Feature Set
+- Part of the `cplace-paw` (Plugin Add-on Widgets) repository
+- Complements document management capabilities in cplace
+- Works alongside other document-related features like file attachments and downloads
+
+## Prerequisites & 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)
+
+## Internationalization
+
+The widget supports multiple languages through property files:
+- English (`messages_en.properties`)
+- German (`messages_de.properties`)
+
+### Localized Messages
+- Widget name: "PDF Preview"
+- Configuration labels: "PDF Reference Attribute", "Show download button", "Show widget frame"
+- User messages:
+  - "Download"
+  - "An error occurred while displaying the file."
+  - "You do not have sufficient access rights to view the referenced file."
+  - "There is no file referenced for display."
+
+## Code References
+
+### Java Classes
+- Widget Definition: `cf.cplace.pdfPreview/src/main/java/cf/cplace/pdfPreview/script/PdfPreviewWidgetDefinition.java:24`
+- Widget State: `cf.cplace.pdfPreview/src/main/java/cf/cplace/pdfPreview/script/PdfPreviewWidgetState.java:23`
+- Configuration Types: `cf.cplace.pdfPreview/src/main/java/cf/cplace/pdfPreview/PdfPreviewWidgetTypes.java:20`
+- Attribute Provider: `cf.cplace.pdfPreview/src/main/java/cf/cplace/pdfPreview/script/PdfAttributeEnumerationProvider.java:19`
+
+### Frontend Files
+- Controller: `cf.cplace.pdfPreview/assets/ts/directives/cfCplacePdfPreview.ts:19`
+- Template: `cf.cplace.pdfPreview/src/main/resources/cf/cplace/pdfPreview/script/pdfPreviewWidgetDefinition.htm:1`
+
+## Summary
+
+The PDF Preview widget is a focused utility widget that provides inline preview of PDF documents referenced through Document attributes. It's ideal for scenarios where seeing the first page of a PDF provides valuable context without requiring users to download or open the full document. The widget offers flexible configuration, respects access permissions, and integrates seamlessly with cplace's widget framework.
+
+**Key Strengths:**
+- Easy to configure with simple attribute selection
+- Respects security and access control
+- Responsive and handles dynamic resizing
+- User-friendly error handling
+- Optional download functionality
+
+**Main Limitation:**
+- Only displays the first page (not suitable for multi-page PDF viewing)