@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/cf.cplace.demoWidgets.demoRichString/_meta.json

@@ -0,0 +1,10 @@
+{
+  "tags": [
+    "rich-text",
+    "container",
+    "low-code",
+    "dashboard",
+    "kpi"
+  ],
+  "requiredApp": null
+}

package/dist/widget-specifications/cf.cplace.demoWidgets.demoRichString/_overview.md

@@ -0,0 +1,200 @@
+## Overview
+
+A frameless widget for displaying styled HTML content that integrates seamlessly with page design. The `content` attribute holds static HTML; to make content **dynamic**, embed `cf.cplace.lowCodeWidgets.lowCodeText` widgets that execute scripts and render output inline.
+
+**Use when**: Dynamic banners, custom breadcrumb navigation, KPI cards, conditional content display, or any content that should appear as native page content without a widget frame.
+
+**Alternative**: Rich String provides similar functionality but with a visible frame - better when users need to recognize the widget.
+
+## Use Cases
+
+### KPI Cards and Dashboard Numbers
+
+Preferred over Highcharts for simple number displays - provides full CSS control without chart library overhead.
+
+```html
+<div style="background: #4CAF50; color: white; padding: 20px; text-align: center; border-radius: 8px;">
+  <div style="font-size: 48px; font-weight: bold;"><!-- Embedded Low-Code widget --></div>
+  <div style="font-size: 14px; margin-top: 8px;">Active Suppliers</div>
+</div>
+```
+
+| Need | Widget Choice |
+|------|---------------|
+| Simple number/count display | **demoRichString** |
+| Bar/pie/line chart, gauge | scriptingHighcharts |
+
+### Dynamic Page Banners
+
+Combine page title with status indicators in full-width banners using solution-specific CSS classes. Embed multiple Low-Code Text widgets for title (localized) and RAG status indicators that render conditionally.
+
+### Custom Breadcrumb Navigation
+
+Generate domain-specific breadcrumb trails when standard cplace navigation is insufficient. Use cplace CSS classes (`cf-cplace-breadcrumbs-wrapper`) and PJAX links (`cplace-pjax-link`) for native appearance and smooth navigation.
+
+### Conditional Content Display
+
+Content that changes based on page attributes or user context. Scripts return empty strings when conditions aren't met, leaving no trace. Supports language detection via `cplace.currentUser.getLanguage()`.
+
+## Embedded Widget Pattern (Widget-in-Widget)
+
+The Rich Text widget acts as a **styled container**, while embedded Low-Code Text widgets (`cf.cplace.lowCodeWidgets.lowCodeText`) provide **dynamic content**.
+
+### Architecture
+
+```
++-------------------------------------------------------------+
+|  Rich Text Widget (demoRichString)                          |
+|  +----------------------------------------------------------+
+|  |  <div class="banner">                                    |
+|  |    <div class="title">                                   |
+|  |      +--------------------------------------+            |
+|  |      | Embedded Low-Code Text Widget #1    | -> Title   |
+|  |      +--------------------------------------+            |
+|  |    </div>                                                |
+|  |    <div class="status">                                  |
+|  |      +--------------------------------------+            |
+|  |      | Embedded Low-Code Text Widget #2    | -> Status  |
+|  |      +--------------------------------------+            |
+|  |    </div>                                                |
+|  |  </div>                                                  |
+|  +----------------------------------------------------------+
++-------------------------------------------------------------+
+```
+
+### How It Works
+
+1. **Container Definition**: The Rich Text widget holds HTML markup with CSS classes for styling
+2. **Embedding Points**: Special widget tags mark where dynamic content should appear
+3. **Widget Configuration**: Each embedded widget is stored as base64-encoded JSON
+4. **Independent Execution**: Each embedded widget runs its script independently
+5. **Inline Rendering**: Output replaces the widget tag in the final HTML
+
+### Embedded Widget Configuration
+
+Each embedded Low-Code Text widget has these key properties:
+
+| Property | Purpose |
+|----------|---------|
+| `dataSource` | How the widget gets page context (`search` or direct reference) |
+| `includeAllSearchResults` | Whether to iterate over multiple pages |
+| `tableSelectionOnly` | Restrict to table selections |
+| `script` | The cplaceJS code that generates HTML output |
+
+### Script Context: `embeddingPage`
+
+**Critical**: Scripts inside embedded widgets access the current page through `embeddingPage`, not `currentPage`.
+
+```javascript
+// Correct - use embeddingPage
+const pageName = embeddingPage.getName();
+const status = embeddingPage.get('cf.cplace.status');
+
+// Wrong - currentPage is undefined in embedded context
+const pageName = currentPage.getName(); // Will fail!
+```
+
+### Script Patterns
+
+**Pattern 1: Localized Title Display**
+```javascript
+const lang = cplace.currentUser.getLanguage();
+const label = lang === 'de' ? 'Planseite' : 'Schedule Page';
+return '<span class="title-label">' + label + ': ' + embeddingPage.getName() + '</span>';
+```
+
+**Pattern 2: Conditional Status Indicator**
+```javascript
+const status = embeddingPage.get('cf.cplace.ratingLight');
+if (!status) return ''; // Nothing displayed when no status
+
+const colors = { 'gruen': 'green', 'gelb': 'yellow', 'rot': 'red' };
+const color = colors[status] || 'gray';
+return '<span class="status-dot" style="background:' + color + '"></span>';
+```
+
+**Pattern 3: Hierarchical Navigation**
+```javascript
+const folder = embeddingPage.get('cf.cplace.rmProjectFolder')
+            ?? embeddingPage.getParent()?.get('cf.cplace.rmProjectFolder');
+const parent = embeddingPage.getParent();
+
+let html = '<nav class="cf-cplace-breadcrumbs-wrapper"><ol class="cf-cplace-breadcrumbs">';
+if (folder) {
+  html += '<li><a href="' + folder.getUrl() + '" class="cplace-pjax-link">'
+       + '<i class="fa fa-folder-tree"></i> ' + folder.getName() + '</a></li>';
+}
+if (parent) {
+  html += '<li><a href="' + parent.getUrl() + '" class="cplace-pjax-link">'
+       + parent.getName() + '</a></li>';
+}
+html += '<li>' + embeddingPage.getName() + '</li></ol></nav>';
+return html;
+```
+
+**Pattern 4: Multi-Language Content**
+```javascript
+const lang = cplace.currentUser.getLanguage();
+const messages = {
+  'en': { welcome: 'Welcome', description: 'This is your project dashboard.' },
+  'de': { welcome: 'Willkommen', description: 'Dies ist Ihr Projekt-Dashboard.' }
+};
+const msg = messages[lang] || messages['en'];
+return '<h2>' + msg.welcome + '</h2><p>' + msg.description + '</p>';
+```
+
+### Best Practices
+
+**Return Empty Strings, Not Null**
+```javascript
+// Good - clean output when condition not met
+if (!shouldShow) return '';
+
+// Bad - may cause rendering issues
+if (!shouldShow) return null;
+if (!shouldShow) return undefined;
+```
+
+**Use Null-Safe Navigation**
+```javascript
+// Good - handles missing attributes gracefully
+const folder = embeddingPage.get('cf.cplace.folder');
+const folderName = folder?.getName() ?? 'Unknown';
+
+// Bad - will throw error if folder is null
+const folderName = embeddingPage.get('cf.cplace.folder').getName();
+```
+
+**Keep Scripts Focused**
+Each embedded widget should do one thing well. For complex displays, use multiple embedded widgets rather than one monolithic script.
+
+### Common Embedded Widget Configurations
+
+| Use Case | Data Source | Script Focus |
+|----------|-------------|--------------|
+| Page Title Display | Direct/Search | `embeddingPage.getName()` with labels |
+| Attribute Values | Direct/Search | Read and format specific attributes |
+| Status Indicators | Direct/Search | Conditional rendering based on status |
+| Navigation Links | Search | Traverse hierarchy, generate link HTML |
+| Localized Messages | Direct | Language detection, message lookup |
+| KPI Counts | Search | Query pages, return formatted count |
+
+## Design Considerations
+
+**Trade-offs**:
+- Frameless design provides visual flexibility but users cannot identify content as widget-generated
+- Embedded widgets add power but complexity - base64 encoding requires tooling support
+- Custom CSS classes must exist in workspace/solution stylesheets
+
+**When NOT to Use**: Users need inline editing (use Rich String), content should be identifiable as widget, simple page title (use Page View Headline), or standard navigation suffices.
+
+**Typical Positioning**: Row 0, full width (12 cols) for banners and navigation. Common layout pairs with `layoutTabsWidget` in Row 1.
+
+## Related Widgets
+
+| Widget | Relationship |
+|--------|-------------|
+| Rich String | Visible frame; better for user-editable content |
+| Page View Headline | Simpler alternative for just page title |
+| Low-Code Text | Embedded within this widget for dynamic content |
+| Layout Tabs Widget | Commonly paired in Row 1 below the header |

package/dist/widget-specifications/cf.cplace.demoWidgets.demoRichString/_summary.md

@@ -0,0 +1 @@
+A frameless widget for styled HTML content. Static by default, but **becomes dynamic when embedding Low-Code widgets** inside the content (Widget-in-Widget pattern). Preferred choice for KPI cards and dashboard numbers - simpler than Highcharts with full CSS control.

package/dist/widget-specifications/cf.cplace.documentation.navigationWidget/_catalog-data.json

@@ -0,0 +1,12 @@
+{
+  "Widget": "cf.cplace.documentation.navigationWidget",
+  "Description": "{\"en\":\"Create a clear overview using freely configurable title and page links.\",\"de\":\"Schaffen Sie Übersichtlichkeit mittels frei konfigurierbarer Titel- und Seitenlinks.\"}",
+  "Localized Name": "{\"en\":\"Title and Page Links\",\"de\":\"Titel und Seitenlinks\"}",
+  "Icon": "fa-sitemap",
+  "Plugin": "cf.cplace.documentation",
+  "App": "cf.cplace.documentation",
+  "Localized App Name": "{\"en\":\"cplace Documentation\",\"de\":\"cplace Dokumentation\"}",
+  "Repository": "cplace-paw",
+  "* Details DE": null,
+  "* Details EN": null
+}

package/dist/widget-specifications/cf.cplace.documentation.navigationWidget/_meta.json

@@ -0,0 +1,10 @@
+{
+  "tags": [
+    "references",
+    "list",
+    "read-only",
+    "navigation",
+    "dashboard"
+  ],
+  "requiredApp": "cf.cplace.documentation"
+}

package/dist/widget-specifications/cf.cplace.documentation.navigationWidget/_overview.md

@@ -0,0 +1,27 @@
+## Overview
+
+Create a clear overview using freely configurable title and page links. The widget displays a prominent title (with optional page link) and a collection of page links in a visually appealing, color-coded tile format with an icon. It is designed to improve navigation in extensive page structures by providing clear visual signposts that reduce cognitive load.
+
+The widget renders as a styled tile with a colored background, featuring an icon on the left side and the title with page link buttons on the right. It supports 24 Material Design-inspired colors and both FontAwesome and cplace custom icons.
+
+## Use Cases
+
+- **Documentation Portal Entry Pages**: Create visually appealing landing pages for documentation areas with clear entry points to different sections
+- **Workspace Navigation Hubs**: Build navigation dashboards that organize content into logical categories and guide users to relevant areas
+- **Content Organization**: Create visual hierarchies for complex content structures by organizing related pages under thematic categories
+- **Landing Page Design**: Design attractive landing pages with multiple navigation tiles using different colors and icons for a dashboard-like experience
+
+## Design Considerations
+
+Key design aspects include:
+
+- **Fixed layout**: Icon positioned on the left (80px width), content on the right
+- **Visual consistency**: 24 predefined color options ensure consistent styling
+- **Minimal chrome**: Renders without frame or padding for seamless page integration
+- **Button limits**: Page link buttons are limited to 200px width with text truncation; recommend 5-8 links for optimal readability
+
+## Alternatives
+
+- **Breadcrumbs Widget** (`cf.cplace.breadcrumbs.breadcrumbsWidget`): For hierarchical path-based navigation
+- **Navigation Tile Widget** (`cf.cplace.navigationTileWidget.widget`): Alternative navigation tile implementation
+- **Landing Page Widgets** (`cf.cplace.landingPageFromPage.*`): For quick overview displays and welcome messages

package/dist/widget-specifications/cf.cplace.documentation.navigationWidget/_summary.md

@@ -0,0 +1 @@
+Create a clear overview using freely configurable title and page links displayed as a styled tile with icon and color-coded background.

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.imageWithTextAndListWidget/_catalog-data.json

@@ -0,0 +1,12 @@
+{
+  "Widget": "cf.cplace.dragAndDropImageView.imageWithTextAndListWidget",
+  "Description": "{\"en\":\"Displays an image that contains additional text and a reference list.\",\"de\":\"Zeigt ein Bild an, das zusätzlichen Text und eine Referenzliste enthält.\"}",
+  "Localized Name": "{\"en\":\"Image with text and list\",\"de\":\"Text mit Bild und Liste\"}",
+  "Icon": "cf-widget",
+  "Plugin": "cf.cplace.dragAndDropImageView",
+  "App": "cf.cplace.platform",
+  "Localized App Name": "{\"en\":\"cplace Basis\",\"de\":\"cplace Basis\"}",
+  "Repository": "cplace-paw",
+  "* Details DE": null,
+  "* Details EN": "<p><strong>More Details</strong></p>\n\n<p>The 'Image with Text and List' widget shows a text and a generated list on top of a background graphic.</p>\n\n<p>The appearance and the positioning of the specified text as well as the scaling of the image can be set.</p>\n\n<p>The list is generated by defining a search. It acts as a navigational aid with each entry being linked to a search result.</p>\n\n<p><strong>Prerequisite</strong></p>\n\n<p>The type of the page to which the 'Image with Text and List' widget should be added must have a relational attribute of type 'File'.</p>\n\n<p>//The file attached to this page is used as the background graphic.</p>\n\n<p><strong>Settings</strong></p>\n\n<p>// * Title: Bilingual text.</p>\n\n<p>// * Reference attribute*:</p>\n\n<p>// * Show widget frame*: True/false.</p>\n\n<p>// * Scaling: Horizontal/Vertical/Fit.</p>\n\n<p>// * Height:</p>\n\n<p>// * Text</p>\n\n<p>// * Text position:</p>\n\n<p>// * Search*:</p>\n\n<p>// * Sort criterion:</p>\n\n<p>// * Sort order: Ascending/descending.</p>\n\n<p>&nbsp;</p>\n\n<p>&nbsp;</p>"
+}

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.imageWithTextAndListWidget/_meta.json

@@ -0,0 +1,10 @@
+{
+  "tags": [
+    "media",
+    "files",
+    "list",
+    "searchable",
+    "drag-drop"
+  ],
+  "requiredApp": null
+}

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.imageWithTextAndListWidget/_overview.md

@@ -0,0 +1,79 @@
+## Overview
+
+Displays an image that contains additional text and a reference list. This widget combines three components: an image display with drag-and-drop upload capability, customizable overlay text positioned on the image, and a search-driven list of pages displayed below the image. It extends the basic image functionality by adding both text overlay and data listing capabilities, making it ideal for visual page headers that also need to display related content.
+
+The widget manages an image through a page attribute reference, displays formatted text overlaid on the image, and shows up to 100 pages matching a search query below the image section.
+
+## Use Cases
+
+### Visual Headers with Related Content
+Create compelling page headers that combine branding imagery, descriptive text, and relevant data listings. For example, a project page might display a project banner image with the project name overlaid, followed by a list of related milestones or deliverables.
+
+### Dashboard Sections
+Build dashboard sections that use images as visual separators or category indicators, with text providing context and a list showing the actual data items. This works well for categorized overviews where each category has its own visual identity.
+
+### Landing Pages with Navigation
+Design landing pages where images represent different areas or modules, with overlay text providing titles or descriptions, and lists showing entry points or featured items within each area.
+
+### Portfolio or Gallery Views
+Present portfolio items or project galleries where each entry has a hero image, descriptive text overlay, and a list of related documents, team members, or sub-items.
+
+## Design Considerations
+
+### When to Use This Widget
+
+- You need a visual header that also displays related data
+- The page structure benefits from combining imagery, text, and listings in one component
+- Related pages should be shown contextually with their visual representation
+- Users need both visual orientation and quick access to related content
+- The image, text, and list are conceptually connected as a single unit
+
+### When NOT to Use This Widget
+
+- You only need image display without text overlay or lists (use `cf.cplace.dragAndDropImageView.widget`)
+- You need text overlay but no list component (use `cf.cplace.dragAndDropImageView.imageWithTextWidget`)
+- The list should be independent from the image (use separate widgets)
+- You need to display more than 100 items in the list (widget has a built-in limit)
+- The list requires complex table functionality like filtering, sorting, or column customization (use table widgets)
+
+### Component Relationships
+
+**Image Component**: Inherits full drag-and-drop upload functionality from the base image widget, including the ability to select from existing page images, remove the current image, and configure scaling modes.
+
+**Text Overlay**: Provides rich text formatting with seven positioning options (top-left, top-center, top-right, center, bottom-left, bottom-center, bottom-right), allowing flexible text placement over the image.
+
+**List Component**: Uses the search mechanism to find and display related pages, with optional sorting by a specific attribute. The list is limited to 100 results and displays pages in a simple sequential format.
+
+### Configuration Dependencies
+
+The widget requires:
+1. A page attribute reference to a Document (for the image)
+2. Text content with positioning (for the overlay)
+3. A search configuration (for the list)
+
+All three components must be configured for the widget to function as intended.
+
+## Common Pitfalls
+
+- **Search Result Limit**: The widget automatically limits list results to 100 pages. If you need to display more items, consider using a dedicated table widget instead.
+- **Text Positioning**: The text overlay uses absolute positioning over the image. Ensure text remains readable across different image backgrounds by using appropriate background colors and padding in the text styling.
+- **Image Aspect Ratios**: When combining images with lists, consider the vertical space allocation. Very tall images may push the list too far down the page.
+- **List Simplicity**: The list component is simple and sequential - it does not support advanced table features like column customization, inline editing, or user-driven filtering.
+
+## Related Patterns
+
+### Widget Family Progression
+
+This widget is part of a three-widget family that progressively adds functionality:
+
+1. **cf.cplace.dragAndDropImageView.widget** - Base image display with upload
+2. **cf.cplace.dragAndDropImageView.imageWithTextWidget** - Adds text overlay to image
+3. **cf.cplace.dragAndDropImageView.imageWithTextAndListWidget** - Adds search-driven list below image and text
+
+Each widget in the family inherits all functionality from its predecessor while adding new capabilities.
+
+### Alternative Patterns
+
+- **Separate Widgets**: Use `cf.cplace.dragAndDropImageView.imageWithTextWidget` and a table widget separately when the list needs advanced functionality or when the image and list should be independently positioned.
+- **Image Gallery with Lists**: For multiple images each with their own lists, use multiple instances of this widget or consider a custom layout solution.
+- **Master-Detail Pattern**: If the list items need to drive detail views, combine this widget with master-detail capable table widgets for more sophisticated navigation patterns.

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.imageWithTextAndListWidget/_summary.md

@@ -0,0 +1 @@
+Displays an image that contains additional text and a reference list. Use for creating visual headers with associated content listings.

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.imageWithTextWidget/_catalog-data.json

@@ -0,0 +1,12 @@
+{
+  "Widget": "cf.cplace.dragAndDropImageView.imageWithTextWidget",
+  "Description": "{\"en\":\"Displays an image that contains an additional text.\",\"de\":\"Zeigt ein Bild an, das einen zusätzlichen Text enthält.\"}",
+  "Localized Name": "{\"en\":\"Image with text\",\"de\":\"Text und Bild\"}",
+  "Icon": "cf-widget",
+  "Plugin": "cf.cplace.dragAndDropImageView",
+  "App": "cf.cplace.platform",
+  "Localized App Name": "{\"en\":\"cplace Basis\",\"de\":\"cplace Basis\"}",
+  "Repository": "cplace-paw",
+  "* Details DE": null,
+  "* Details EN": "<p><strong>More Details</strong></p>\n\n<p>The 'Image with Text' widget shows a specified text with a background graphic.</p>\n\n<p>The appearance and the positioning of the text as well as the scaling of the image can be set.</p>\n\n<p><strong>Prerequisites</strong></p>\n\n<p>The type of the page to which the 'Image with Text and List' widget should be added must have a relational attribute of type 'File'.</p>\n\n<p><strong>Settings</strong></p>\n\n<p>// * Title: Bilingual text.</p>\n\n<p>// * Reference attribute*:</p>\n\n<p>// * Show widget frame*: True/false.</p>\n\n<p>// * Scaling: Horizontal/Vertical/Fit.</p>\n\n<p>// * Height:</p>\n\n<p>// * Text:</p>\n\n<p>// * Text position: Bottom left, Bottom centered, Bottom right, Top left, Top centered, Top right, Centered.</p>\n\n<p>&nbsp;</p>"
+}

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.imageWithTextWidget/_meta.json

@@ -0,0 +1,10 @@
+{
+  "tags": [
+    "media",
+    "rich-text",
+    "drag-drop",
+    "inline-edit",
+    "detail-view"
+  ],
+  "requiredApp": null
+}

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.imageWithTextWidget/_overview.md

@@ -0,0 +1,176 @@
+## Overview
+
+Displays an image that contains an additional text. The widget extends the basic drag-and-drop image viewer by adding configurable text overlay functionality. It enables users to display images with descriptive or contextual text positioned on top of the image with rich HTML formatting support. The widget combines all the functionality of the base Image widget (upload, selection, removal, scaling, lightbox) with additional text overlay capabilities including flexible positioning and dynamic content from page attributes.
+
+## Use Cases
+
+### Primary Use Cases
+
+1. **Hero Banners with Captions**: Display promotional images with title text or call-to-action overlays
+   - Example: Project landing page with "Welcome to Project X" overlaid on banner image
+
+2. **Labeled Visual Content**: Add descriptive text to images for context
+   - Example: Process diagram with "Phase 1: Planning" overlaid on diagram section
+
+3. **Call-to-Action Images**: Combine visual appeal with actionable text
+   - Example: Feature image with "Learn More" or "Get Started" button text
+
+4. **Annotated Screenshots**: Add explanatory text to screenshots or documentation images
+   - Example: UI screenshot with "Click here to start" pointing to a specific area
+
+5. **Status Indicators**: Display dynamic status text over visual representations
+   - Example: Project status board with status text overlaid on project image
+
+6. **Marketing/Communication Pages**: Create visually rich communication with minimal effort
+   - Example: News article with headline overlaid on featured image
+
+7. **Dashboard Headers**: Combine visual branding with key metrics or titles
+   - Example: Department dashboard with department name overlaid on theme image
+
+### When to Use This Widget
+
+Use this widget when:
+- You need to display a **single image with text** on a page
+- The text should be **positioned on/over the image** (not beside it)
+- You want **rich text formatting** (colors, fonts, sizes, links)
+- The text content may need to be **dynamic** (from page attributes)
+- Users need **easy upload and management** of the image
+- You want a **professional, modern appearance** with text overlays
+
+### When NOT to Use This Widget
+
+Avoid this widget when:
+- Text should appear **beside or below** the image (consider using layout containers)
+- You need to display **multiple images** (consider image gallery widgets)
+- The text is very long (overlays work best with short, impactful text)
+- You need complex text layouts or multiple text blocks (consider separate text widgets)
+- Read-only image display without upload capability (consider simpler image display widgets)
+
+## Design Considerations
+
+### Text Overlay Design Principles
+
+**Visual Cohesion**: Text overlays treat text and image as a single visual unit, providing space efficiency and modern, magazine-style layouts that draw attention to specific parts of the image.
+
+**HTML Support for Rich Formatting**: The widget supports HTML in text overlays, allowing emphasis (bold, italic, underline), brand colors, actionable links, structured information with lists, and font size hierarchy for future-proof formatting needs.
+
+**Positioning Options**: Multiple position choices enable compositional balance, visual hierarchy (center for primary messages, corners for secondary), adaptability to different image "safe zones", and support for various use cases (headers, captions, labels).
+
+### Common Configuration Patterns
+
+1. **Title Overlay Pattern**
+   - Position: Bottom-left or Center
+   - Style: Large, bold text with semi-transparent dark background
+   - Use case: Hero sections, feature highlights
+
+2. **Caption Pattern**
+   - Position: Bottom-left or Bottom-right
+   - Style: Smaller text, possibly italicized
+   - Use case: Photo credits, image descriptions
+
+3. **Call-to-Action Pattern**
+   - Position: Center or Bottom-center
+   - Style: Button-like appearance with contrasting colors
+   - Use case: Interactive elements, navigation prompts
+
+4. **Labeled Diagram Pattern**
+   - Position: Top-left or Top-center
+   - Style: Simple, clean text, minimal background
+   - Use case: Process documentation, phase indicators
+
+5. **Status Dashboard Header Pattern**
+   - Position: Top-right or Bottom-right
+   - Style: Color-coded text (red/yellow/green), medium size
+   - Use case: Dashboards, status boards, monitoring pages
+
+### Best Practices
+
+**Image Selection**:
+- Choose images with **clear areas** for text placement
+- Avoid overly busy backgrounds where text will appear
+- Consider **aspect ratio** when selecting scaling mode
+- Use high-quality images that scale well
+
+**Text Content**:
+- Keep text **short and impactful** (headlines, not paragraphs)
+- Use **clear, readable fonts** at appropriate sizes
+- Ensure **high contrast** between text and image background
+- Test readability at different screen sizes
+
+**Text Positioning**:
+- Position text in **visually quiet areas** of the image
+- Follow **compositional rules** (rule of thirds, etc.)
+- Consider **reading patterns** (left-to-right, top-to-bottom)
+- Avoid covering important image content
+
+**Styling for Readability**:
+- Use **semi-transparent backgrounds** behind text when needed
+- Apply **text shadows** or outlines for contrast
+- Choose **large enough font sizes** for easy reading
+- Test on **different devices** and screen sizes
+
+**Dynamic Text Usage**:
+- Validate that **attribute values are appropriate length**
+- Provide **default/fallback text** if attribute is empty
+- Consider **formatting rules** for attribute content
+- Document expected attribute content format
+
+## Limitations and Constraints
+
+### Text Overlay Constraints
+
+**Text Length**: Long text may not fit well on images with no automatic text wrapping controls, and readability decreases with longer content.
+
+**HTML Complexity**: Complex HTML structures may not render well in overlay, limited space constrains layout possibilities, and there may be HTML sanitization restrictions for security.
+
+**Positioning Limitations**: Fixed position options (not pixel-perfect placement), may not align perfectly with specific image features, and position behavior may vary with different image sizes.
+
+**Readability Challenges**: Text may be hard to read on busy image backgrounds, requires careful color/contrast choices, and may need semi-transparent backgrounds for legibility.
+
+**Dynamic Text Considerations**: Attribute-based text may change length unexpectedly, no validation that text fits in chosen position, and requires attribute read permissions.
+
+### Inherited Constraints
+
+From the base Image widget:
+- Must be a reference attribute to Document type
+- Must have "At most one value" multiplicity
+- Only embeddable in Page entities
+- Single image only
+- Relies on platform file upload restrictions
+
+## Related Widgets
+
+### Widget Family
+
+This widget is part of a three-widget family:
+
+1. **cf.cplace.dragAndDropImageView.widget** (Image)
+   - Base widget: Image display with upload
+   - No text overlay
+   - Choose when: You just need image display and upload
+
+2. **cf.cplace.dragAndDropImageView.imageWithTextWidget** (Image with text) - **THIS WIDGET**
+   - Extends base widget
+   - Adds text overlay with positioning and HTML formatting
+   - Single image focus
+   - Choose when: You need text overlaid on image
+
+3. **cf.cplace.dragAndDropImageView.imageWithTextAndListWidget** (Image with text and list)
+   - Extends image with text widget
+   - Adds search/list component below the image
+   - Combines image header with related entity list
+   - Choose when: You need image + text + related entities list
+
+### Comparison with Alternatives
+
+**vs. Base Image Widget**:
+- Choose Image with Text when you need text on the image, not beside it
+- Base widget is simpler but lacks text overlay and HTML formatting capabilities
+
+**vs. Separate Image + Text Widgets**:
+- Image with Text provides visual cohesion as a single unit and better space efficiency
+- Separate widgets offer more flexible placement options but use more vertical space and require two configurations
+
+**vs. Image with Text and List Widget**:
+- Image with Text is more focused and uses less vertical space
+- Image with Text and List is better when you need to display related entities below the image

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.imageWithTextWidget/_summary.md

@@ -0,0 +1 @@
+Displays an image that contains an additional text with customizable positioning and rich HTML formatting support.

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.widget/_catalog-data.json

@@ -0,0 +1,12 @@
+{
+  "Widget": "cf.cplace.dragAndDropImageView.widget",
+  "Description": "{\"en\":\"Displays an image from a file reference attribute and allows easy drag-and-drop upload.\",\"de\":\"Zeigt ein Bild aus einem Dateireferenzattribut an und ermöglicht ein einfaches Hochladen per Drag-and-Drop.\"}",
+  "Localized Name": "{\"en\":\"Image\",\"de\":\"Bild\"}",
+  "Icon": "cf-widget",
+  "Plugin": "cf.cplace.dragAndDropImageView",
+  "App": "cf.cplace.platform",
+  "Localized App Name": "{\"en\":\"cplace Basis\",\"de\":\"cplace Basis\"}",
+  "Repository": "cplace-paw",
+  "* Details DE": null,
+  "* Details EN": "<p><strong>More Details</strong></p>\n\n<p>The 'Image' widget enables you to add and display a single image on a page.</p>\n\n<p><strong>Prerequisite</strong></p>\n\n<p>The type of the page to which the image should be added must have a relational attribute of type 'File'.</p>\n\n<p><strong>Settings</strong></p>\n\n<p>// * Title: Bilingual text.</p>\n\n<p>// * Reference attribute*:</p>\n\n<p>// * Show widget frame*:</p>\n\n<p>// * Scaling: Horizontal, Vertical, Fit.</p>\n\n<p>// * Height:</p>\n\n<p>&nbsp;</p>\n\n<p>&nbsp;</p>\n\n<p>&nbsp;</p>"
+}

package/dist/widget-specifications/cf.cplace.dragAndDropImageView.widget/_meta.json

@@ -0,0 +1,10 @@
+{
+  "tags": [
+    "media",
+    "drag-drop",
+    "inline-edit",
+    "detail-view",
+    "files"
+  ],
+  "requiredApp": null
+}