@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-platform-richString/research.md

@@ -0,0 +1,437 @@
+# Widget Research: cf.platform.richString
+
+## Overview
+
+**Widget ID:** `cf.platform.richString`
+**Widget Name:** Text
+**Repository:** main
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/RichStringWidgetDefinition.java`
+
+## Purpose
+
+The Rich String widget provides a way to display formatted HTML content (rich text) with a customizable title in a framed widget container. It allows users to create text-based content with rich formatting capabilities including bold, italic, lists, links, and embedded elements.
+
+## Description
+
+The Rich String widget is a versatile text display and editing component that renders HTML-formatted content in a titled frame. It serves as a standalone content widget that can be placed on pages to display formatted text, create documentation sections, add announcements, or provide instructional content. The widget uses a rich text editor (CKEditor) for content creation and supports the full range of HTML formatting options while ensuring security through content sanitization.
+
+## Use Cases
+
+### 1. Documentation and Instructions
+- Add formatted documentation sections to pages
+- Provide step-by-step instructions with numbered or bulleted lists
+- Create help text or guidance for complex processes
+- Include explanatory content with headings, paragraphs, and formatting
+- **Example:** Adding a "How to Use" section to a project management page with formatted instructions
+
+### 2. Announcements and Notices
+- Display important announcements with prominent formatting
+- Add warning or information boxes with colored text or highlights
+- Create attention-grabbing messages using bold, italic, or underlined text
+- Include time-sensitive information that needs to stand out
+- **Example:** Adding a project status update with highlighted key dates and bold text for important milestones
+
+### 3. Rich Content Pages
+- Build content-rich landing pages with multiple text sections
+- Create knowledge base articles with formatted content
+- Develop informational dashboards with text explanations
+- Design onboarding pages with structured content
+- **Example:** Creating a team wiki page with multiple sections covering different topics
+
+### 4. Meeting Notes and Summaries
+- Capture and display meeting minutes with structured formatting
+- Create executive summaries with bullet points and highlights
+- Document decisions and action items with clear formatting
+- Archive discussion notes with proper structure
+- **Example:** Recording a sprint planning meeting with formatted notes, action items, and decisions
+
+### 5. Embedded Content with Links
+- Add content sections that link to other pages or external resources
+- Create navigation or reference sections with hyperlinks
+- Embed rich text content that references other entities in the system
+- Build content hubs that connect related information
+- **Example:** Creating a resources section with links to related projects, documents, and external websites
+
+### 6. Formatted Reports and Summaries
+- Display project status summaries with rich formatting
+- Create executive dashboards with formatted text blocks
+- Present analysis results with structured text content
+- Show KPI descriptions with formatting for clarity
+- **Example:** Adding a project health summary with color-coded status indicators and formatted metrics
+
+### 7. HTML Content Embedding
+- Embed custom HTML content within the widget
+- Display specialized formatting not available in standard text widgets
+- Include tables, custom styling, or advanced HTML elements
+- Create visually appealing content layouts
+- **Example:** Embedding a custom-formatted table showing team responsibilities
+
+## Key Functionality
+
+### Rich Text Content
+
+The widget's primary feature is displaying HTML-formatted content:
+- **HTML Rendering:** Supports full HTML markup with security sanitization
+- **Rich Formatting:** Bold, italic, underline, strikethrough, colors, fonts, sizes
+- **Structure:** Headings (H1-H6), paragraphs, lists (ordered/unordered), blockquotes
+- **Links:** Hyperlinks to internal pages, external URLs, or entity references
+- **Media:** Images can be embedded within the content
+- **Tables:** Support for formatted tables within the rich text
+- **Code:** Can display code blocks or inline code formatting
+
+### Content Security
+
+The widget implements robust security measures:
+- **HTML Sanitization:** Uses `StringFilterUtilities.sanitize()` to strip forbidden characters
+- **Tag Cleaning:** Uses `RichStringUtilities.clean()` to remove forbidden HTML tags and attributes
+- **XSS Protection:** Prevents cross-site scripting attacks through content filtering
+- **Safe Rendering:** Only allows whitelisted HTML elements and attributes
+
+### Title Display
+
+The widget includes a configurable title:
+- **Localized Title:** Supports multi-language titles via `localizedTitle` configuration
+- **Prominent Display:** Title appears in the widget frame header
+- **Optional:** Can be configured with or without a title
+- **Dynamic Translation:** Automatically displays in the user's selected language
+
+### Frame Presentation
+
+The widget is displayed in a standard widget frame:
+- **Visual Container:** Bordered frame with title bar
+- **Consistent Styling:** Matches other platform widgets in appearance
+- **Fixed or Dynamic Height:** Can specify custom height or use default sizing
+- **Widget Context:** Full widget chrome with standard controls
+
+## Configuration Concepts
+
+### Required Configuration
+
+1. **Localized Title** (`localizedTitle`)
+   - Multi-language title displayed in the widget frame
+   - Type: `SingleLocalizedStringAttributeDef`
+   - Multiplicity: Exactly one (required)
+   - Purpose: Provides a descriptive label for the widget content
+   - Replaces deprecated `title` attribute
+
+2. **Content** (`content`)
+   - The HTML-formatted rich text content to display
+   - Type: `SingleRichStringAttributeDef`
+   - Multiplicity: Maximal one (optional)
+   - Purpose: Contains the actual formatted text with HTML markup
+   - Edited using a rich text editor (CKEditor 5)
+   - Automatically cleaned and sanitized on save
+
+### Optional Configuration
+
+3. **Height** (`height`)
+   - Custom height in pixels for the widget
+   - Type: `SingleNumberAttributeDef`
+   - Multiplicity: Maximal one (optional)
+   - Purpose: Allows manual control of widget vertical size
+   - Default: Uses platform default widget height if not specified
+   - Useful for ensuring consistent sizing or accommodating large content
+
+## Configuration Details
+
+### Widget Type Definition
+
+The widget configuration is defined by the `cf.richString` type with three attributes:
+- `localizedWidgetTitle` (localized string, exactly one)
+- `content` (rich string, maximal one)
+- `height` (number, maximal one)
+
+### Content Editing
+
+The content is edited using a rich text editor interface:
+- **Editor:** CKEditor 5 (newer instances) or legacy CKEditor
+- **WYSIWYG:** What-you-see-is-what-you-get editing experience
+- **Toolbar:** Full formatting toolbar with all standard options
+- **Widget Embedding:** Other widgets can be embedded within the rich text content
+- **Link Support:** Create hyperlinks to pages, entities, or external URLs
+
+### Fulltext Search
+
+The widget content is fully searchable:
+- `configurationValuesAreFulltextSearchable()` returns `true`
+- Content is indexed for platform-wide search
+- Users can find pages containing specific text within these widgets
+- Helps with knowledge discovery and content findability
+
+## Related Widgets
+
+### Similar Widgets in the Platform
+
+1. **cf.platform.customRichStringAttribute** (Custom Rich String Attribute Widget)
+   - Displays a specific rich string attribute from a custom entity
+   - Connected to entity data model
+   - Shows attribute value rather than static content
+   - Used for displaying rich string fields from data records
+   - Icon: `fa-pen-square`
+
+2. **cf.cplace.demoWidgets.demoRichString** (Rich String Without Frame)
+   - Demo/test variant that displays rich content without the widget frame
+   - Same content capabilities but different presentation
+   - Used for frameless/embedded scenarios
+   - Testing and demonstration purposes
+
+### Relationship to Rich String Attributes
+
+Rich String is both a widget type and an attribute type in the platform:
+- **As Attribute:** Custom types can have rich string attributes for formatted text fields
+- **As Widget:** This widget displays static rich text content on pages
+- **Custom Attribute Widget:** The `customRichStringAttribute` widget bridges these concepts
+- **Shared Technology:** Both use the same `RichStringValue` class and security measures
+
+### Content vs. Attribute Widgets
+
+Key distinction from attribute widgets:
+- **Static Content:** This widget stores content in the widget configuration itself
+- **Attribute Display:** Other widgets display content from entity attributes
+- **Use Case:** Use this widget for page-level content, not entity-specific data
+- **Independence:** This widget's content is independent of any data model
+
+## Technical Architecture
+
+### Backend Components
+
+- **Definition Class:** `RichStringWidgetDefinition`
+  - Extends `WidgetDefinition`
+  - Widget kind: `cf.platform.richString`
+  - Icon: `fa-font` (Font Awesome font/text icon)
+  - Embeddable: Only as a widget on pages (not in other contexts)
+  - Part of: Platform core application (`PlatformPlugin.platformApp`)
+
+- **Substitution Class:** `RichStringWidgetSubstitution`
+  - Extends `WidgetPrintSubstitution`
+  - Handles widget rendering and content processing
+  - Uses `Escaping.none` for HTML content preservation
+  - Implements `print()` method to render content via `FunctionsHelper`
+  - Provides `getTitle()` for dynamic title display
+
+- **Content Processing:**
+  - Content is processed through `FunctionsHelper.proxy("richStringContent", ...)`
+  - Uses `RichStringValue.valueOf()` for content validation and sanitization
+  - Passes `assetUid` parameter for context (entity UID of the page)
+  - Template: `richStringValue/richStringContent.htm` renders the HTML
+
+- **Type Definition:** `RICH_STRING_WIDGET.TYPE`
+  - Type name: `cf.richString`
+  - Three attributes: `LOCALIZED_TITLE`, `CONTENT`, `HEIGHT`
+  - Provides configuration schema for the widget
+
+### Frontend Components
+
+The widget uses CKEditor for content editing:
+- **Editor Controllers:**
+  - `AbstractEditRichStringCtrl` - Base controller for rich string editing
+  - `EditCustomSingleRichStringCtrl` - Controller for custom attribute editing
+  - `EditBuiltinRichStringCtrl` - Controller for built-in rich string editing
+
+- **Rendering:**
+  - Content is rendered in a `div` with class `tricia-richstring`
+  - CKEditor 5 adds additional classes: `ck ck-content`
+  - HTML content is inserted directly (already sanitized)
+  - CSS styling via platform stylesheets
+
+### Data Flow
+
+1. **Configuration:** User configures title and content in widget settings
+2. **Storage:** Configuration stored in widget configuration entity
+3. **Rendering Request:** Page rendering triggers widget substitution
+4. **Content Processing:**
+   - `RichStringWidgetSubstitution.init()` loads configuration
+   - `RichStringWidgetSubstitution.print()` processes content
+   - `RichStringValue.valueOf()` validates and sanitizes HTML
+   - `FunctionsHelper.proxy()` renders via template
+5. **Template Application:** `richStringContent.htm` wraps content in styled div
+6. **Output:** HTML rendered in widget frame with title
+
+### Security Architecture
+
+Multi-layered security approach:
+1. **Input Validation:** `RichStringValue.valueOf()` validates on creation
+2. **HTML Cleaning:** `RichStringUtilities.clean()` removes dangerous tags/attributes
+3. **Character Sanitization:** `StringFilterUtilities.sanitize()` strips forbidden characters
+4. **Placeholder on Empty:** Uses `U+FFFC` (Object Replacement Character) if content becomes empty
+5. **Exception on Invalid:** Throws `IllegalStateException` if content is invalid
+6. **No Escaping:** Uses `Escaping.none` because content is pre-sanitized
+
+## Prerequisites and Dependencies
+
+### Prerequisites
+- Widget must be embedded on a page (not in other contexts)
+- Users need appropriate page editing permissions to add/configure the widget
+- Users need permissions to view the page to see the widget content
+
+### Dependencies
+- **CKEditor:** Rich text editor library for content editing
+  - CKEditor 5 (modern instances)
+  - Legacy CKEditor (older instances)
+- **HTML Sanitization:** Platform security utilities
+  - `RichStringUtilities` for HTML cleaning
+  - `StringFilterUtilities` for character sanitization
+- **Templating Engine:** Platform template system for rendering
+- **Widget Framework:** Core widget infrastructure for embedding and display
+
+### Browser Requirements
+- Modern browser with JavaScript enabled
+- CSS support for rich text rendering
+- CKEditor compatible browser (Chrome, Firefox, Safari, Edge)
+
+## Migration Notes
+
+The widget supports migration from older configurations:
+- **Deprecated Attribute:** `title` (SingleStringAttributeDef) is deprecated
+- **New Attribute:** `localizedTitle` (SingleLocalizedStringAttributeDef) replaces it
+- **Migration Method:** `migrateWidgetConfiguration()` automatically converts old configurations
+- **Migration Function:** `migrateUnlocalizedStringToLocalizedString()` handles the conversion
+- **Backward Compatibility:** Old configurations continue to work and are upgraded automatically
+- **No Data Loss:** Title values are preserved during migration
+
+## Best Practices
+
+### When to Use Rich String Widget
+
+**Use when:**
+- You need to add formatted text content to a page
+- You want to display static informational content with styling
+- You need to create documentation or help sections
+- You want to add announcements or notices with formatting
+- You need to embed links to other pages or resources
+- You want consistent, framed presentation of text content
+
+**Avoid when:**
+- You need to display entity attribute values (use `customRichStringAttribute` instead)
+- You need dynamic content that updates with data changes
+- You want to display large amounts of continuously updated content
+- You need interactive or editable content for end users
+- You want frameless content (consider `demoRichString` variant)
+
+### Content Creation Best Practices
+
+1. **Keep It Concise:** Avoid extremely long text blocks; break into multiple widgets
+2. **Use Structure:** Leverage headings, lists, and paragraphs for readability
+3. **Meaningful Titles:** Provide clear, descriptive titles that explain the content
+4. **Link Appropriately:** Use hyperlinks to connect to related content
+5. **Consider Mobile:** Keep formatting simple for mobile viewing
+6. **Avoid Complex HTML:** Stick to standard formatting rather than custom HTML
+7. **Test Rendering:** Preview content to ensure it displays as intended
+
+### Configuration Recommendations
+
+1. **Localized Titles:** Configure titles in all supported languages for internationalization
+2. **Set Height Strategically:**
+   - Use default height for most content
+   - Set custom height for very long content to avoid excessive scrolling
+   - Match heights across widgets for visual consistency
+3. **Content Organization:**
+   - Use one widget per logical content section
+   - Combine related information within a single widget
+   - Separate distinct topics into different widgets
+4. **Consistent Styling:** Use similar formatting across widgets on the same page
+5. **Security Awareness:** Be aware that content is sanitized; complex HTML may be stripped
+
+### Accessibility Considerations
+
+1. **Semantic HTML:** Use proper heading hierarchy (H1-H6) for screen readers
+2. **Link Text:** Use descriptive link text, not "click here"
+3. **Alt Text:** If embedding images, provide alt text (within editor)
+4. **Color Contrast:** Ensure sufficient contrast for colored text
+5. **Lists:** Use proper list formatting for better navigation
+
+## Common Use Case Examples
+
+### Example 1: Project Overview Section
+- **Title:** "Project Overview"
+- **Content:** Formatted description with bullet points covering scope, timeline, and key stakeholders
+- **Height:** Default
+- **Scenario:** Providing context at the top of a project page
+
+### Example 2: Important Announcement
+- **Title:** "⚠️ System Maintenance Notice"
+- **Content:** Bold text with dates, colored highlighting for important details, link to more information
+- **Height:** Default (compact)
+- **Scenario:** Time-sensitive notification on a dashboard
+
+### Example 3: Instructions and Help
+- **Title:** "How to Submit a Request"
+- **Content:** Numbered list with step-by-step instructions, embedded links to forms
+- **Height:** Custom (400px) to accommodate longer content
+- **Scenario:** Help section on a request submission page
+
+### Example 4: Meeting Minutes
+- **Title:** "Sprint Planning - January 16, 2026"
+- **Content:** Structured content with attendees, agenda items (headers), discussion notes, and action items (bulleted)
+- **Height:** Custom (600px) for comprehensive notes
+- **Scenario:** Meeting documentation on a team page
+
+### Example 5: Reference Links Section
+- **Title:** "Related Resources"
+- **Content:** Bulleted list of hyperlinks to related pages, documents, and external sites
+- **Height:** Default
+- **Scenario:** Navigation aid at bottom of a page
+
+## Comparison with Similar Widgets
+
+| Feature | cf.platform.richString | cf.platform.customRichStringAttribute | cf.cplace.demoWidgets.demoRichString |
+|---------|----------------------|-----------------------------------|-----------------------------------|
+| Purpose | Static formatted text | Entity attribute display | Frameless rich text demo |
+| Content Source | Widget configuration | Entity attribute value | Widget configuration |
+| Frame | Yes (standard widget) | Optional (configurable) | No (frameless) |
+| Data Binding | None | Bound to entity | None |
+| Use Case | Page content | Data field display | Testing/demo |
+| Icon | fa-font | fa-pen-square | fa-font |
+| Updates | Manual edit | Updates with entity | Manual edit |
+
+## Limitations and Considerations
+
+### Technical Limitations
+1. **Static Content:** Content doesn't update dynamically based on data changes
+2. **No Versioning:** No built-in version history for content changes
+3. **HTML Restrictions:** Some HTML elements and attributes are stripped for security
+4. **Size Constraints:** Very large content may impact page load performance
+5. **Single Language in Editor:** Content itself is not localized, only the title
+
+### Security Considerations
+1. **Sanitization Required:** All content is automatically sanitized, custom scripts removed
+2. **XSS Prevention:** Cannot execute JavaScript or embed dangerous content
+3. **Limited HTML:** Only safe HTML elements and attributes are allowed
+4. **Content Review:** Consider reviewing content from multiple contributors
+
+### Performance Considerations
+1. **Rich Content Size:** Large amounts of formatted content can slow page rendering
+2. **Image Embedding:** Embedded images should be optimized for web
+3. **Widget Count:** Many rich string widgets on one page may impact performance
+4. **Search Indexing:** Content is indexed, contributing to search index size
+
+## Error Handling
+
+### Common Errors and Messages
+
+1. **Empty Content After Sanitization**
+   - **Error:** `IllegalStateException` - "An empty value is not allowed"
+   - **Cause:** Content becomes empty after HTML cleaning or sanitization
+   - **Resolution:** Add valid text content, avoid content that consists only of forbidden elements
+
+2. **Invalid HTML Structure**
+   - **Behavior:** Malformed HTML is cleaned/corrected automatically
+   - **Result:** Content may not render exactly as entered
+   - **Resolution:** Use editor toolbar rather than raw HTML editing
+
+3. **Missing Title**
+   - **Behavior:** Widget requires a localized title
+   - **Resolution:** Configuration validation ensures title is provided
+
+### Validation
+
+The widget performs validation at multiple stages:
+- **Configuration Validation:** Ensures required fields (title) are present
+- **Content Validation:** `RichStringValue.valueOf()` validates HTML content
+- **Embedding Validation:** `checkIsEmbeddedAsWidget()` ensures proper context
+
+## Summary
+
+The Rich String widget (`cf.platform.richString`) is a fundamental content widget in the cplace platform that enables users to add formatted HTML content with titles to pages. It provides a secure, user-friendly way to create rich text sections for documentation, announcements, instructions, and general informational content. The widget leverages CKEditor for content creation while implementing robust security measures through HTML sanitization and content validation.
+
+With its framed presentation, localized title support, and full rich formatting capabilities, the Rich String widget is ideal for creating structured, professional-looking content sections on pages. It complements data-driven widgets by providing static content areas that enhance page usability and provide context for the information displayed in other widgets. The widget's search indexing and migration support make it a reliable choice for long-term content management within the cplace platform.