@cplace/mcp-server 1.6.0 → 1.6.1

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

@@ -1,194 +0,0 @@
-# Research: Widget `cf.cplace.demoWidgets.demoRichString`
-
-**Widget ID:** `cf.cplace.demoWidgets.demoRichString`
-**Widget Name:** Text without widget frame
-**Repository:** main
-**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/RichStringWithoutFrameWidgetDefinition.java`
-
----
-
-## 1. Purpose
-
-The `cf.cplace.demoWidgets.demoRichString` widget is a specialized text widget that displays formatted rich text content without the standard widget frame/border, creating a seamless visual integration into the page layout.
-
-**Short Description:**
-A frameless widget for displaying formatted rich text with an optional title, editable only through the layout settings, designed for seamless content integration into page layouts.
-
----
-
-## 2. Core Functionality
-
-### Key Characteristics
-
-1. **Frameless Display**
-   - The widget explicitly disables the standard widget frame by returning `false` in its `showFrame()` method (RichStringWithoutFrameWidgetSubstitution.java:102-104)
-   - This creates a borderless appearance that blends seamlessly into the page
-
-2. **Rich Text Rendering**
-   - Supports formatted text content including bold, italic, lists, links, and other rich text formatting
-   - Content is rendered using the platform's `richStringContent` function (RichStringWithoutFrameWidgetSubstitution.java:98)
-
-3. **Edit Restrictions**
-   - Content is **only editable through the layout/widget settings**, not through direct page editing
-   - This is explicitly mentioned in the widget description: "(Editable only in layout.)"
-
-4. **Localized Title Support**
-   - Supports multilingual titles through `LocalizedString` (RichStringWithoutFrameWidgetSubstitution.java:84-85)
-   - Titles are optional and can be configured per widget instance
-
-5. **Fulltext Searchability**
-   - Widget content is included in fulltext search results (RichStringWithoutFrameWidgetDefinition.java:43-45)
-
----
-
-## 3. Use Cases
-
-### Primary Use Cases
-
-1. **Static Content Sections**
-   - Displaying informational text blocks that shouldn't look like widgets
-   - Adding explanatory content that blends naturally into the page
-   - Creating instructions or help text within a page layout
-
-2. **Visual Design & Layout**
-   - Creating clean, frame-free text sections for modern UI designs
-   - Building custom page layouts where widget borders would be visually distracting
-   - Designing landing pages or dashboards with seamless text integration
-
-3. **Content That Rarely Changes**
-   - Since editing requires accessing layout settings (not inline editing), this widget is ideal for content that:
-     - Is set up once during page design
-     - Changes infrequently
-     - Should not be easily editable by regular users
-
-4. **Structured Information Display**
-   - Displaying policy text, guidelines, or documentation
-   - Showing formatted announcements or notices
-   - Presenting structured content with headings, lists, and formatted text
-
-### When NOT to Use
-
-- **Frequently Updated Content:** The layout-only editing makes it inconvenient for content that changes often
-- **User-Generated Content:** Not suitable for content that users need to edit directly on the page
-- **Interactive Elements:** This is a display-only widget; use other widgets for interactive features
-
----
-
-## 4. Configuration Concepts
-
-### Main Configuration Options
-
-The widget has three primary configuration attributes (defined in RichStringWithoutFrameWidgetSubstitution.java:26-66):
-
-1. **Title (Localized)**
-   - **Attribute:** `localizedWidgetTitle`
-   - **Type:** `LocalizedString`
-   - **Multiplicity:** At most one (optional)
-   - **Purpose:** Optional multilingual title displayed above the content
-   - **Note:** Replaces deprecated non-localized `widgetTitle` attribute
-
-2. **Content**
-   - **Attribute:** `content`
-   - **Type:** `RichString`
-   - **Multiplicity:** At most one (optional)
-   - **Purpose:** The main rich text content with formatting
-   - **Supports:** Bold, italic, lists, links, headings, and other rich text formatting
-
-3. **Height**
-   - **Attribute:** `height`
-   - **Type:** `Number`
-   - **Multiplicity:** At most one (optional)
-   - **Purpose:** Fixed height for the widget (in pixels or other units)
-   - **Use Case:** Useful for creating consistent layouts with fixed-height content areas
-
-### Customization Capabilities
-
-- **Formatting:** Full rich text formatting through the cplace rich text editor
-- **Multilingual Support:** Title can be localized for different languages
-- **Size Control:** Height can be explicitly set for layout consistency
-- **No Runtime Editing:** Content cannot be edited directly on the page, only through widget configuration
-
----
-
-## 5. Context & Relationships
-
-### Related Widgets
-
-1. **`cf.platform.richString` (RichStringWidget)**
-   - The standard rich text widget **with a frame**
-   - Similar functionality but displays a widget border/frame
-   - Defined in RichStringWidgetDefinition.java:27
-   - Use when you want the standard widget appearance
-
-2. **Comparison with Standard RichString Widget**
-
-   | Aspect | demoRichString (Without Frame) | richString (Standard) |
-   |--------|-------------------------------|----------------------|
-   | Frame/Border | No (`showFrame()` returns false) | Yes (default widget frame) |
-   | Visual Integration | Seamless, blends into page | Distinct widget appearance |
-   | Title Requirement | Optional (maximalOne) | Required (exactlyOne) |
-   | Use Case | Clean layouts, static content | Standard widget usage |
-   | Widget ID | `cf.cplace.demoWidgets.demoRichString` | `cf.platform.richString` |
-
-3. **CustomRichStringAttributeWidget**
-   - Displays rich text attribute values from entities
-   - Different purpose: shows data from entity attributes rather than static configured content
-
-### Widget Family
-
-This widget belongs to the **text/content display widget family** within the cplace platform:
-- Shares configuration structure with standard RichStringWidget
-- Uses the same rendering mechanism (`richStringContent` function)
-- Part of the platform's core widget set (defined in `cf.cplace.platform`)
-
-### Technical Dependencies
-
-- **App:** Platform App (`PlatformPlugin.INSTANCE().platformApp`)
-- **Icon:** Font Awesome "fa-font" icon
-- **Rendering:** Uses `FunctionsHelper.proxy("richStringContent", ...)` for content rendering
-- **Entity Context:** Content rendering includes the entity UID for proper asset handling
-
----
-
-## 6. Key Technical Details
-
-### Class Structure
-
-**Definition Class:** `RichStringWithoutFrameWidgetDefinition`
-- Location: cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/RichStringWithoutFrameWidgetDefinition.java:23
-
-**Substitution Class:** `RichStringWithoutFrameWidgetSubstitution`
-- Location: cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/RichStringWithoutFrameWidgetSubstitution.java:24
-- Handles content rendering and title display
-
-### Migration Support
-
-The widget includes migration logic for transitioning from the deprecated non-localized title to the localized version:
-- Old: `widgetTitle` (String)
-- New: `localizedWidgetTitle` (LocalizedString)
-- Migration method: `migrateUnlocalizedStringToLocalizedString()` (RichStringWithoutFrameWidgetDefinition.java:91)
-
-### Embedding Constraints
-
-- Can only be embedded as a widget (not in other contexts)
-- Checked via `checkIsEmbeddedAsWidget()` method (RichStringWithoutFrameWidgetDefinition.java:74)
-
----
-
-## 7. Localization
-
-The widget supports full internationalization:
-
-**English:**
-- Name: "Text without widget frame"
-- Description: "A widget without frame to enter formatted text with a title. (Editable only in layout.)"
-
-**German:**
-- Name: "Text ohne Widget-Rahmen"
-- Description: "Ein Widget ohne Rahmen für die Eingabe von formatiertem Text. (Nur über die Einstellungen bearbeitbar.)"
-
----
-
-## Summary
-
-The `cf.cplace.demoWidgets.demoRichString` widget is designed for displaying formatted text content that should visually blend into the page without the typical widget border. It's ideal for static or semi-static content that rarely changes, such as informational sections, guidelines, or design elements in custom page layouts. The key distinguishing feature is the absence of the widget frame, making it perfect for creating clean, modern UI designs where traditional widget borders would be visually disruptive.

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

@@ -1,426 +0,0 @@
-# Widget Research: cf.cplace.documentation.navigationWidget
-
-**Research Date:** 2026-01-16
-**Widget ID:** `cf.cplace.documentation.navigationWidget`
-**Widget Name:** Title and Page Links
-**Repository:** cplace-paw
-**Plugin:** cf.cplace.documentation
-
----
-
-## 1. Widget Purpose
-
-### Core Functionality
-
-The **Documentation Navigation Widget** is a visual navigation component designed to create clear entry points and navigation aids within cplace workspaces. It 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.
-
-### Short Description
-
-This widget creates a styled navigation tile that combines a title, multiple page links, and an icon to provide intuitive navigation entry points for documentation and content structures.
-
-### Technical Implementation
-
-- **Definition Class:** `cf.cplace.documentation/src/main/java/cf/cplace/documentation/script/DocumentationWidgetDefinition.java`
-- **Icon:** `fa-sitemap` (representing a hierarchical navigation structure)
-- **Frame Display:** No frame (`showFrame() = false`)
-- **Padding:** No padding (`isNoPadding() = true`)
-- **Template:** `documentationWidgetDefinition.htm`
-
----
-
-## 2. Use Cases
-
-### Primary Use Cases
-
-1. **Documentation Portal Entry Pages**
-   - Create visually appealing landing pages for documentation areas
-   - Provide clear entry points to different documentation sections
-   - Example: A "User Documentation" tile linking to Getting Started, Tutorials, FAQ, and Reference pages
-
-2. **Workspace Navigation Hubs**
-   - Build navigation dashboards that organize content into logical categories
-   - Guide users to relevant content areas within extensive page structures
-   - Example: A project workspace with tiles for "Planning", "Execution", "Reporting", each linking to related pages
-
-3. **Content Organization and Structure**
-   - Create visual hierarchies for complex content structures
-   - Organize related pages under thematic categories
-   - Example: An onboarding page with tiles for different department introductions
-
-4. **Landing Page Design**
-   - Design attractive landing pages with multiple navigation tiles
-   - Combine multiple widget instances with different colors and icons to create a dashboard-like experience
-   - Example: A company intranet homepage with tiles for HR, IT Support, News, and Resources
-
-### Problem Statement
-
-**Problem Solved:** In extensive cplace workspaces with many pages and complex hierarchies, users struggle to find and navigate to relevant content. Traditional navigation methods (breadcrumbs, page trees) can be overwhelming or buried in the interface.
-
-**Solution:** The Documentation Navigation Widget provides visually distinct, prominently placed navigation tiles that act as clear signposts. The combination of color, icon, and organized page links makes navigation intuitive and reduces cognitive load.
-
----
-
-## 3. Configuration Concepts
-
-### Configuration Attributes
-
-The widget is configured through the `NAVIGATION_WIDGET` type definition with the following attributes:
-
-#### 1. Title Text (`cf.cplace.documentation.titleText`)
-- **Type:** Single String (optional)
-- **Purpose:** Display text for the widget's main heading
-- **Multiplicity:** Maximum one
-- **Example:** "Getting Started", "User Documentation", "Project Resources"
-
-#### 2. Title Page (`cf.cplace.documentation.titlePage`)
-- **Type:** Single Page Reference (optional)
-- **Purpose:** Makes the title clickable and links to a target page
-- **Multiplicity:** Maximum one
-- **Behavior:** If configured, the title becomes a hyperlink; otherwise, it displays as plain text
-- **Use Case:** Link the title to an overview or main page for the category
-
-#### 3. Pages (`cf.cplace.documentation.pages`)
-- **Type:** Multi Page Reference
-- **Purpose:** Collection of pages displayed as navigation buttons below the title
-- **Multiplicity:** Multiple (any number)
-- **Rendering:** Each page appears as a flat button with white border
-- **Display:** Shows page name, truncated if necessary (max 200px width)
-
-#### 4. Icon (`cf.cplace.documentation.icon`)
-- **Type:** Single String with Icon Constraint
-- **Purpose:** Visual identifier displayed on the left side of the widget
-- **Default Value:** `cf-cplace`
-- **Supported Formats:**
-  - FontAwesome icons (prefix: `fa-`)
-  - cplace custom icons (prefix: `cf-`)
-- **Example Values:** `fa-book`, `fa-graduation-cap`, `cf-cplace`, `fa-wrench`
-
-#### 5. Color (`cf.cplace.landingPage.color`)
-- **Type:** Text Enumeration (optional)
-- **Purpose:** Background color scheme for the widget tile
-- **Multiplicity:** Maximum one
-- **Available Options:** 24 Material Design-inspired colors including:
-  - Primary colors: Red, Blue, Green, Yellow, Orange, Pink, Purple
-  - Variants: Dark-Red, Light-Blue, Dark-Blue, Light-Green, Dark-Green
-  - Neutral: Grey, Blue-Grey, Brown, White
-  - Additional: Indigo, Cyan, Teal, Lime, Amber, Deep-Orange, Deep-Purple
-- **Visual Effect:** The color affects both the widget background and icon tile shading
-
-### Configuration Behavior
-
-- **Title Display Logic:** The widget intelligently handles three scenarios:
-  1. Both `titleText` and `titlePage` configured: Displays clickable title text linking to the page
-  2. Only `titlePage` configured: Displays the page name as a clickable link
-  3. Only `titleText` configured: Displays plain text title (not clickable)
-
-- **Icon Processing:** The template automatically prepends the appropriate CSS class prefix (`fa` or `cf`) based on the first two characters of the icon value
-
-- **Color Scheme:** Each color option provides:
-  - Main background color (500 shade from Material Design palette)
-  - Icon tile background (400 shade)
-  - Icon color (500 shade)
-  - Hover effects on page buttons
-
----
-
-## 4. Context and Relationships
-
-### Plugin Context
-
-The widget is part of the **cf.cplace.documentation** plugin, which is described as supporting "the creation of clear entry pages for easier navigation in extensive page structures through the free configurability of titles and page links."
-
-**Plugin Details:**
-- **Display Name:** cplace Documentation
-- **Group:** cf.cplace
-- **Repository:** cplace-paw (Platform Add-on Widgets)
-- **Icon:** fa-info
-
-### Related Widgets
-
-The Documentation Navigation Widget is part of a broader ecosystem of landing page and navigation widgets in cplace:
-
-1. **Landing Page Widgets** (cf.cplace.landingPageFromPage plugin):
-   - `cf.cplace.landingPageFromPage.quickOverview` - Quick overview displays
-   - `cf.cplace.landingPageFromPage.sessionUserNameWidget` - Welcome messages
-   - `cf.cplace.landingPageFromPage.simpleListWithAttachment` - List displays with attachments
-
-2. **Navigation Widgets**:
-   - `cf.cplace.breadcrumbs.breadcrumbsWidget` - Breadcrumb navigation
-   - `cf.cplace.navigationTileWidget.widget` - Alternative navigation tile
-
-### Widget Positioning in Ecosystem
-
-- **Category:** Navigation and Documentation widgets
-- **Complexity Level:** Medium (requires understanding of page references and visual design)
-- **Target Users:** Workspace administrators, content managers, documentation creators
-- **Typical Page Types:** Landing pages, dashboard pages, portal entry pages
-
-### Prerequisites and Dependencies
-
-- **Dependencies:** Only requires cf.cplace.platform (core platform)
-- **Page Requirements:** Works on any page where widgets can be placed
-- **Content Requirements:** Benefits from having multiple related pages to link to
-- **User Permissions:** Users viewing the widget need read access to referenced pages
-
----
-
-## 5. Visual Design and Styling
-
-### Layout Structure
-
-```
-┌─────────────────────────────────────────────┐
-│ [Icon Tile]  Main Title (clickable)         │
-│   [Icon]                                     │
-│   80x100%    [Button] [Button] [Button]     │
-│              [Button] [Button]               │
-└─────────────────────────────────────────────┘
-```
-
-### Key Styling Features
-
-1. **Widget Container:**
-   - Rounded corners (10px border-radius)
-   - Minimum height: 155px
-   - Colored background based on selected color scheme
-   - No frame or padding around the widget itself
-
-2. **Icon Tile:**
-   - Fixed width: 80px
-   - Height: Full widget height
-   - Positioned on the left side
-   - Rounded corners (10px)
-   - Slightly lighter shade than main background
-   - Icon centered vertically
-
-3. **Title:**
-   - Large font size (2em)
-   - White color
-   - Text truncation with ellipsis if too long
-   - Positioned at the top with 13px padding
-
-4. **Page Buttons:**
-   - Flat style with white border
-   - White text on transparent background
-   - Hover effect: white background with colored text
-   - Maximum width: 200px with text truncation
-   - Spacing: 13px margin bottom, 6.5px margin right
-   - Padding: 6px vertical, 20px horizontal
-
-### CSS Classes
-
-- `.cf-cplace-documentation-wrapper` - Outer container
-- `.cf-cplace-documentation-widget-row` - Main widget row with color variants
-- `.icon-tile` - Icon container
-- `.sub-pages` - Container for page link buttons
-- Color-specific classes: `.Red`, `.Blue`, `.Green`, etc.
-
----
-
-## 6. Technical Details
-
-### Configuration Type Definition
-
-Located in: `cf.cplace.documentation.DocumentationWidgetTypes.NAVIGATION_WIDGET`
-
-```java
-public static final TypeDef TYPE = new TypeDef(
-    "cf.cplace.documentation.navigationWidget",
-    TITLE_TEXT,
-    TITLE_PAGE,
-    PAGES,
-    ICON,
-    COLOR
-);
-```
-
-### Template Substitutions
-
-The widget provides the following template substitutions:
-
-- `titleText` - The configured title text
-- `titlePageUrl` - Absolute URL of the title page
-- `titlePage` - Page object for the title link
-- `pages` - List of page references for navigation buttons
-- `icon` - Processed icon class string
-- `color` - Selected color scheme
-
-### Rendering Notes
-
-- Widget renders without a frame or padding for seamless integration into page layouts
-- Page names are displayed using `$p.name()$` template function
-- Page URLs are generated using `$p.url()$` for relative links and `getAbsoluteUrl()` for title pages
-- The template handles conditional rendering based on which fields are configured
-
----
-
-## 7. Best Practices and Recommendations
-
-### Configuration Best Practices
-
-1. **Title Configuration:**
-   - Use clear, concise titles (2-4 words)
-   - Consider linking the title to an overview or index page
-   - Example: "User Guides" linking to a user guide overview page
-
-2. **Page Selection:**
-   - Limit to 5-8 page links for optimal readability
-   - Select pages of similar importance/hierarchy level
-   - Order pages logically (e.g., Getting Started → Intermediate → Advanced)
-
-3. **Color and Icon Selection:**
-   - Use colors consistently across related widgets
-   - Choose icons that clearly represent the content category
-   - Consider accessibility when selecting color combinations
-
-4. **Layout Design:**
-   - Combine multiple navigation widgets to create dashboard layouts
-   - Use different colors to visually distinguish different content areas
-   - Place on landing pages or workspace entry points
-
-### Common Patterns
-
-1. **Documentation Portal Pattern:**
-   - Multiple navigation widgets on one page
-   - Each widget represents a documentation category
-   - Different colors for different categories
-
-2. **Hierarchical Navigation Pattern:**
-   - Title links to parent/overview page
-   - Page links lead to child pages
-   - Creates clear parent-child relationship
-
-3. **Dashboard Pattern:**
-   - Grid layout of navigation widgets
-   - Each widget represents a functional area
-   - Consistent styling with varying colors and icons
-
----
-
-## 8. Example Scenarios
-
-### Scenario 1: IT Support Portal
-
-**Configuration:**
-- **Title Text:** "IT Support"
-- **Title Page:** Link to IT Support Overview page
-- **Pages:**
-  - Request Access
-  - Report Issue
-  - FAQ
-  - Contact IT
-- **Icon:** fa-wrench
-- **Color:** Blue
-
-**Use Case:** Employees need quick access to IT support resources from the company intranet homepage.
-
-### Scenario 2: Project Documentation Hub
-
-**Configuration:**
-- **Title Text:** "Project Alpha Documentation"
-- **Title Page:** Link to Project Alpha main page
-- **Pages:**
-  - Project Charter
-  - Requirements
-  - Architecture
-  - Meeting Notes
-  - Deliverables
-- **Icon:** fa-folder-open
-- **Color:** Green
-
-**Use Case:** Project team members need organized access to all project documentation from the project workspace.
-
-### Scenario 3: Employee Onboarding
-
-**Configuration:**
-- **Title Text:** "Welcome to the Team!"
-- **Title Page:** Link to Welcome page
-- **Pages:**
-  - First Day Checklist
-  - Company Policies
-  - Benefits Information
-  - Team Directory
-  - Training Schedule
-- **Icon:** fa-graduation-cap
-- **Color:** Purple
-
-**Use Case:** New employees need a clear starting point with organized access to onboarding materials.
-
----
-
-## 9. Limitations and Considerations
-
-### Current Limitations
-
-1. **Fixed Layout:**
-   - Icon position is fixed on the left
-   - Layout is not configurable (always horizontal with icon left, content right)
-   - No option for vertical layouts or alternative arrangements
-
-2. **Button Display:**
-   - Page buttons are simple flat buttons with limited styling options
-   - No option for custom button colors or icons
-   - Button text truncation at 200px may cut important information
-
-3. **Title Constraints:**
-   - Single-line title with text truncation
-   - No subtitle or description field
-   - Limited typography options
-
-4. **Color Limitations:**
-   - Color applies to entire widget
-   - No option for custom color values (limited to 24 predefined colors)
-   - Color attribute references `cf.cplace.landingPage.color` (suggests possible refactoring artifact)
-
-### Performance Considerations
-
-- Minimal performance impact (static rendering, no dynamic JavaScript)
-- Page reference resolution happens during rendering
-- Suitable for dashboards with many instances
-
-### Accessibility Considerations
-
-- Color should not be the only means of differentiation
-- Consider contrast ratios when selecting colors
-- Ensure page link text is descriptive enough for screen readers
-
----
-
-## 10. Summary
-
-### Key Takeaways
-
-1. **Primary Purpose:** Create visual navigation entry points with styled tiles combining titles, page links, and icons
-
-2. **Main Benefits:**
-   - Improves navigation in complex page structures
-   - Provides clear visual hierarchy
-   - Reduces cognitive load through organized presentation
-   - Enhances landing page aesthetics
-
-3. **Ideal For:**
-   - Documentation portals and hubs
-   - Landing pages and dashboards
-   - Workspace entry points
-   - Content organization and navigation
-
-4. **Configuration Simplicity:**
-   - Medium complexity
-   - Requires understanding of page references
-   - Visual configuration (color, icon) is straightforward
-   - Flexible title configuration options
-
-### Integration with cplace
-
-This widget exemplifies cplace's approach to low-code page design, allowing administrators to create professional, functional navigation interfaces without custom development. It fits into the broader ecosystem of landing page and navigation widgets that enable users to build intuitive, visually appealing workspace entry points.
-
----
-
-## Source Files
-
-- **Widget Definition:** `/cf.cplace.documentation/src/main/java/cf/cplace/documentation/script/DocumentationWidgetDefinition.java`
-- **Configuration Types:** `/cf.cplace.documentation/src/main/java/cf/cplace/documentation/DocumentationWidgetTypes.java`
-- **Template:** `/cf.cplace.documentation/src/main/resources/cf/cplace/documentation/script/documentationWidgetDefinition.htm`
-- **Styling:** `/cf.cplace.documentation/assets/less/plugin.less`
-- **Messages (EN):** `/cf.cplace.documentation/src/main/resources/cf/cplace/documentation/messages_en.properties`
-- **Messages (DE):** `/cf.cplace.documentation/src/main/resources/cf/cplace/documentation/messages_de.properties`