@cplace/test-mcp-server 0.1.15 → 1.1.0

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)