@cplace/mcp-server 1.6.0 → 1.6.1

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

@@ -1,525 +0,0 @@
-# Widget Research: cf.cplace.platform.attributesGroup
-
-**Date:** 2026-01-16
-**Widget ID:** `cf.cplace.platform.attributesGroup`
-**Widget Name:** Grouped Attributes of a Page
-**Repository:** main
-**Definition Class:** `/Users/thomasbuechner/dev/repos/main/cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/AttributesGroupWidgetDefinition.java`
-
----
-
-## 1. Purpose
-
-### What This Widget Does
-
-The Attributes Group widget allows users to flexibly arrange and display attributes of a page in a custom layout. Unlike the standard Attributes widget which displays all attributes in a predefined format, this widget gives users full control over which attributes to display and how to arrange them visually using rows and columns.
-
-**Official Description (from messages_en.properties:4230):**
-> "Allows the flexible arrangement of attributes on a page."
-
-### Core Functionality
-
-The widget provides:
-1. **Custom Layout Control**: Define rows and columns to arrange attributes exactly as needed
-2. **Flexible Data Source**: Display attributes from different pages (embedding page, referenced page, or absolute selection)
-3. **Embedded Widget Support**: Can contain other widgets that display individual attributes (e.g., Single Attribute widgets)
-4. **Multi-Edit Capability**: Optionally allows editing of the displayed attributes
-5. **Responsive Display**: Supports both old and new frontend implementations
-
----
-
-## 2. Use Cases
-
-### Primary Use Cases
-
-1. **Custom Attribute Layout for Forms**
-   - Create structured forms with specific attribute groupings
-   - Arrange related attributes in logical sections
-   - Example: Personal info in left column, contact details in right column
-
-2. **Displaying Referenced Entity Attributes**
-   - Show attributes from a page referenced by the current page
-   - Example: Display project details when viewing a task that references the project
-   - Uses reference attributes to navigate to the target entity
-
-3. **Read-Only Attribute Display**
-   - Present attributes in a structured, read-only format
-   - Disable multi-edit to prevent modifications
-   - Useful for summary views or dashboards
-
-4. **Parent Entity Attribute Display**
-   - Show attributes from a parent page
-   - Useful in hierarchical structures where child pages need to display parent information
-
-5. **Flexible Attribute Presentation**
-   - Control visual presentation with frame/no-frame options
-   - Adjust height and spacing
-   - Create custom user experiences beyond standard attribute widgets
-
-### When to Use This Widget
-
-Choose this widget when you need:
-- **Layout Control**: Specific positioning of attributes beyond default layouts
-- **Multiple Columns**: Side-by-side attribute display
-- **Mixed Content**: Combination of different attribute types and widgets
-- **Referenced Data**: Display attributes from related pages
-- **Custom Forms**: Tailored data entry or display experiences
-
-### When NOT to Use This Widget
-
-Use alternatives when:
-- **All Attributes Needed**: Use `cf.platform.attributes` (Attributes widget) for complete attribute display
-- **Single Attribute**: Use `cf.platform.singleAttribute` for individual attribute display
-- **Table Data**: Use `cf.cplace.platform.connectedAttributesGroup` (Grouped Attributes of a Table) for table row data
-- **Simple Display**: Standard attributes widget may be simpler for basic needs
-
----
-
-## 3. Configuration Concepts
-
-### Main Configuration Options
-
-#### 3.1 Title Configuration
-
-**Attributes:**
-- `TITLE` (LocalizedString, optional): Localized title displayed in the widget frame
-- `SHOW_FRAME` (Boolean, default: true): Whether to display a frame around the widget
-
-**Purpose:** Controls the visual presentation and labeling of the widget container.
-
-#### 3.2 Data Source Selection (PAGE_SELECTION)
-
-The widget supports three modes for selecting which page's attributes to display:
-
-**a) Embedding Page (Default)**
-- Shows attributes of the page where the widget is embedded
-- Group: `EmbeddingSinglePageSelectionGroup`
-- No additional configuration needed
-
-**b) Absolute Selection**
-- Explicitly select any page in the system
-- Group: `AbsoluteSinglePageSelectionGroup`
-- Attribute: `ABSOLUTE_SELECTION` (Page Reference, required when selected)
-- Use case: Display attributes from a specific, known page
-
-**c) Relative Selection (From Attribute)**
-- Select a page through a reference attribute on the embedding page
-- Group: `RelativeSinglePageSelectionGroup`
-- Attribute: `RELATIVE_SELECTION` (String enumeration, required when selected)
-- Use case: Display attributes from a page referenced by the current page
-- Example: Show project attributes on a task page via the task's "project" reference attribute
-
-**Implementation:** Uses `AttributeGroupingAttributeDef` with `SinglePageSelectionGrouping` (WidgetTypes.java:1201-1209)
-
-#### 3.3 Layout Configuration
-
-**Attribute:** `LAYOUT` (Layout Constraint)
-
-**Purpose:** Defines the structure of rows, columns, and embedded widgets within the attributes group.
-
-**Structure:**
-- Layout consists of rows
-- Each row contains columns with proportions
-- Each column contains embedded widgets
-- Widgets are typically Single Attribute widgets or other compatible widgets
-
-**Key Classes:**
-- `WidgetContainer`: Holds the layout structure
-- `DummyWidgetContainer`: Temporary container for embedded widget configurations
-- Layout is stored and managed through `LayoutConstraint` (WidgetTypes.java:1228-1232)
-
-#### 3.4 Edit Behavior
-
-**Attribute:** `ENABLE_MULTI_EDIT` (Boolean, default: true)
-
-**Purpose:** Controls whether users can edit the displayed attributes within the widget.
-
-**Behavior:**
-- `true`: Attributes are editable (if user has edit permissions)
-- `false`: Display is read-only
-- Also respects page-level permissions
-- Backend handler: `SubmitAttributesGroupHandler`
-
-#### 3.5 Display Options
-
-**SINGLE_COLUMN** (Boolean, copied from SingleAttributeWidgetDefinition)
-- Affects layout presentation
-- Inherited from `SingleAttributeWidgetDefinition.CONFIGURATION.SINGLE_COLUMN`
-
-**HEIGHT** (Number, optional)
-- Fixed height for the widget
-- From `BASE_MIXIN.HEIGHT`
-- Returns via `fixedHeightAttributeDefOrNull()` method
-
-#### 3.6 Frontend Implementation
-
-**Attribute:** `USE_NEW_FRONTEND` (Boolean)
-
-**Purpose:** Toggle between old and new frontend rendering implementations.
-
-**Behavior:**
-- New frontend: Uses `GroupedAttributesWidgetState` and React components
-- Old frontend: Uses AngularJS controller (`AttributesGroupWidgetCtrl`)
-- Includes on-the-fly migration for backward compatibility (AttributesGroupWidgetDefinition.java:246-250)
-
----
-
-## 4. Technical Implementation
-
-### Backend Components
-
-#### 4.1 Widget Definition Class
-**File:** `AttributesGroupWidgetDefinition.java`
-**Location:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/`
-
-**Key Methods:**
-- `getWidgetKind()`: Returns `"cf.cplace.platform.attributesGroup"`
-- `getConfigurationType()`: Returns `ATTRIBUTES_GROUP.TYPE`
-- `getContentSubstitution()`: Generates widget state and rendering data
-- `isAllowedInLayout()`: Determines which widgets can be embedded
-- `migrateWidgetConfiguration()`: Handles backward compatibility for old configurations
-- `getWidgetState()`: Generates state for new frontend (returns `GroupedAttributesWidgetState`)
-
-#### 4.2 Configuration Type Definition
-**File:** `WidgetTypes.java`
-**Location:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/templating/`
-**Section:** `ATTRIBUTES_GROUP` class (lines 1139-1263)
-
-**Type Definition Includes:**
-```java
-TypeDef TYPE = new TypeDef(
-    "cf.cplace.platform.attributesGroup",
-    UNLOCALIZED_TITLE,  // deprecated
-    TITLE,
-    SHOW_FRAME,
-    SINGLE_COLUMN,
-    ABSOLUTE_SELECTION,
-    RELATIVE_SELECTION,
-    PAGE_SELECTION,
-    ENABLE_MULTI_EDIT,
-    LAYOUT,
-    HEIGHT,
-    USE_NEW_FRONTEND
-);
-```
-
-#### 4.3 Submit Handler
-**File:** `SubmitAttributesGroupHandler.java`
-**Location:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/widget/`
-
-**Purpose:** Processes form submissions when attributes are edited within the widget.
-
-**Parameters:**
-- `PARAMETER_EMBEDDING_UID`: UID of the page containing the widget
-- `PARAMETER_WIDGET_ID`: Unique ID of the widget instance
-- `PARAMETER_SELECTED_UID`: UID of the entity being edited (if different from embedding page)
-
-**Process:**
-1. Resolves the target entity based on data source configuration
-2. Validates edit permissions
-3. Applies configuration migrations for backward compatibility
-4. Processes attribute updates via `AbstractSubmitEditableBlockHandler`
-
-#### 4.4 Data Source Selection Groups
-
-**Base Interface:** `SinglePageSelectionGroup`
-**Location:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/singlepageselectionattributegrouping/`
-
-**Implementations:**
-1. **EmbeddingSinglePageSelectionGroup**: Returns the embedding page
-2. **AbsoluteSinglePageSelectionGroup**: Returns explicitly selected page
-3. **RelativeSinglePageSelectionGroup**: Resolves page through reference attribute
-
-**Configuration:** `SinglePageSelectionConfiguration` manages grouping (WidgetTypes.java:1207)
-
-### Frontend Components
-
-#### 4.5 AngularJS Controller (Old Frontend)
-**File:** `AttributesGroupWidgetCtrl.ts`
-**Location:** `cf.cplace.platform/assets/ts/controllers/groupedAttributes/`
-
-**Controller Name:** `cf.cplace.platform.controllers.AttributesGroupWidgetCtrl`
-
-**Key Functionality:**
-- Extends `EditableBlockCtrl` for form handling
-- Tracks embedding page UID and reference attribute information
-- Listens for reload events (`EVENT_RELOAD_ATTRIBUTES_GROUP_WIDGET`)
-- Responds to attribute updates when data source is a reference attribute
-- Refreshes widget when referenced page changes
-
-**State Interface:**
-```typescript
-interface IAttributesGroupWidgetState extends IEditableBlockState {
-  embeddingPageUid: string;
-  referenceName?: string;  // When showing attributes from referenced page
-  referenceNameIdHash?: string;
-}
-```
-
-#### 4.6 Widget State (New Frontend)
-**DTOs:**
-- `GroupedAttributesWidgetState`: Overall widget state
-- `GroupedAttributesWidgetRow`: Row structure
-- `GroupedAttributesWidgetColumn`: Column structure with proportion
-- `GroupedAttributesWidgetEmbeddedWidget`: Individual embedded widget state
-
-**State Generation:**
-- `getWidgetState()` method processes layout configuration
-- Traverses widget container structure
-- Generates state for each embedded widget
-- Handles invalid configurations with error messages
-
----
-
-## 5. Relationships to Other Widgets
-
-### 5.1 Embedded Widgets
-
-The Attributes Group widget acts as a **container widget** that can embed other widgets. Common embedded widgets include:
-
-1. **cf.platform.singleAttribute** (Single Attribute)
-   - Most common embedded widget
-   - Displays individual attributes
-   - Can be arranged in the layout
-
-2. **cf.platform.connectedSingleAttribute** (Connected Single Attribute)
-   - Similar to Single Attribute but for connected/table data
-   - Frontend treats it identically to Single Attribute (AttributesGroupWidgetDefinition.java:543-545)
-
-3. **Custom Widgets**
-   - Any widget that implements `canBeEmbeddedInsideWidgetOfType(AttributesGroupWidgetDefinition.class)`
-   - Checked via `isAllowedInLayout()` method
-
-### 5.2 Related Widgets
-
-1. **cf.cplace.platform.connectedAttributesGroup** (Grouped Attributes of a Table)
-   - Similar concept but for table/search results
-   - Shows attributes from a selected row in a table widget
-   - Shares layout configuration structure
-   - Description: "Allows you to position the attributes from a table flexibly." (messages_en.properties:4243-4244)
-
-2. **cf.platform.attributes** (Attributes)
-   - Standard attributes widget showing all attributes
-   - No custom layout capability
-   - Simpler to configure but less flexible
-   - Description: "Shows all attributes of a page and allows you to edit them." (messages_en.properties:4233)
-
-3. **cf.platform.singleAttribute** (Single Attribute)
-   - Displays a single attribute
-   - Often used as embedded widget within Attributes Group
-   - Can specify target entity and attribute name
-
-### 5.3 Widget Embedding Rules
-
-**From AttributesGroupWidgetDefinition.java:224-226:**
-```java
-public boolean isAllowedInLayout(WidgetDefinition widgetDefinition) {
-    return widgetDefinition.canBeEmbeddedInsideWidgetOfType(AttributesGroupWidgetDefinition.class);
-}
-```
-
-This method determines which widgets can be placed in the layout. Widgets must explicitly declare support for embedding in AttributesGroup widgets.
-
----
-
-## 6. Key Code References
-
-### Backend Files
-
-1. **Widget Definition**
-   - `AttributesGroupWidgetDefinition.java:63-549`
-   - Main widget implementation
-
-2. **Configuration Type**
-   - `WidgetTypes.java:1139-1263`
-   - ATTRIBUTES_GROUP configuration class
-
-3. **Submit Handler**
-   - `SubmitAttributesGroupHandler.java:1-150`
-   - Form submission processing
-
-4. **Data Source Groups**
-   - `SinglePageSelectionGroup.java` (interface)
-   - `EmbeddingSinglePageSelectionGroup.java`
-   - `AbsoluteSinglePageSelectionGroup.java`
-   - `RelativeSinglePageSelectionGroup.java`
-
-### Frontend Files
-
-5. **AngularJS Controller**
-   - `AttributesGroupWidgetCtrl.ts:1-66`
-   - Old frontend implementation
-
-6. **State DTOs**
-   - `GroupedAttributesWidgetState.java`
-   - `GroupedAttributesWidgetRow.java`
-   - `GroupedAttributesWidgetColumn.java`
-   - `GroupedAttributesWidgetEmbeddedWidget.java`
-
-### Localization
-
-7. **Messages**
-   - `messages_en.properties:4230-4232`
-   - Widget name and description
-
----
-
-## 7. Migration and Backward Compatibility
-
-### Deprecated Attributes
-
-The widget includes several deprecated attributes for backward compatibility:
-
-1. **UNLOCALIZED_TITLE** (deprecated)
-   - Old: Single string title
-   - New: `TITLE` (LocalizedString)
-   - Migration: `migrateUnlocalizedStringToLocalizedString()` (AttributesGroupWidgetDefinition.java:232)
-
-2. **TARGET_ENTITY** (deprecated)
-   - Old: Direct page reference
-   - New: `PAGE_SELECTION` with `ABSOLUTE_SELECTION`
-   - Migration: `migrateTargetEntityToDataSource()` (AttributesGroupWidgetDefinition.java:234, 259-288)
-
-3. **USE_PARENT** (deprecated)
-   - Old: Boolean flag to use parent page
-   - New: `PAGE_SELECTION` with `RELATIVE_SELECTION` (parent attribute)
-   - Migration: Handled in `migrateTargetEntityToDataSource()`
-
-### Migration Strategy
-
-**Method:** `migrateWidgetConfiguration()` (AttributesGroupWidgetDefinition.java:229-237)
-
-**Process:**
-1. Migrate title from unlocalized to localized string
-2. Migrate old data source attributes to new PAGE_SELECTION grouping
-3. Set default value for USE_NEW_FRONTEND if not present
-
-**Frontend Migration:**
-The `USE_NEW_FRONTEND` attribute defaults to `false` for existing widgets, preventing validation errors when old configurations are rendered with new code (AttributesGroupWidgetDefinition.java:240-250).
-
----
-
-## 8. Icon and Visual Representation
-
-**Icon Name:** `cf-pencil-group`
-**Location:** `AttributesGroupWidgetDefinition.java:93`
-
-This icon represents the widget in the cplace UI, typically showing a pencil (edit) icon with a grouping indicator.
-
----
-
-## 9. Implementation Notes
-
-### Layout Structure
-
-The layout is managed through a hierarchical structure:
-```
-AttributesGroupWidget
-  └─ WidgetContainer
-      └─ Layout
-          └─ Row[]
-              └─ Column[]
-                  └─ Widget[]
-```
-
-**Implementation Details:**
-- Layout stored via `LayoutConstraint` (constraint-based storage)
-- `DummyWidgetContainer` used during configuration and rendering
-- Container registered/unregistered from cache as needed (AttributesGroupWidgetDefinition.java:466, 505)
-
-### State Generation
-
-**New Frontend State Generation (AttributesGroupWidgetDefinition.java:408-461):**
-1. Resolve data source (embedding page, absolute selection, or relative selection)
-2. Check if target page is null → show error message
-3. Retrieve layout configuration
-4. Traverse layout structure (rows → columns → widgets)
-5. For each embedded widget:
-   - Get widget configuration
-   - Get widget definition
-   - Generate widget state via `getWidgetState()`
-   - Add to column
-6. Return `GroupedAttributesWidgetState` with all row/column/widget data
-
-**Error Handling:**
-- If reference attribute doesn't resolve to a page: Show localized error (messages_en.properties:4232)
-- If configuration incomplete: Show generic incomplete configuration message
-- If embedded widget has invalid config: Mark in state and show error
-
-### Edit Permissions
-
-Edit capability determined by multiple factors:
-1. `ENABLE_MULTI_EDIT` configuration (must be true)
-2. Target entity edit permissions (`!target.getEntityPermissions().mayEdit()`)
-3. User permissions on embedding and target entities
-
-**Code Reference:** `AttributesGroupWidgetDefinition.java:151-163`
-
----
-
-## 10. Summary
-
-### Quick Facts
-
-| Property | Value |
-|----------|-------|
-| Widget ID | `cf.cplace.platform.attributesGroup` |
-| Widget Name | Grouped Attributes of a Page |
-| Primary Purpose | Flexible attribute arrangement with custom layouts |
-| Container Widget | Yes - embeds other widgets |
-| Data Sources | 3 modes: embedding page, absolute selection, relative (reference attribute) |
-| Edit Support | Yes - configurable via ENABLE_MULTI_EDIT |
-| Frontend | Dual implementation (old AngularJS + new React) |
-| Icon | cf-pencil-group |
-
-### Configuration Summary
-
-**Essential Configuration:**
-1. **Data Source** (PAGE_SELECTION): Which page's attributes to display
-2. **Layout** (LAYOUT): Row/column structure with embedded widgets
-
-**Optional Configuration:**
-- Title (localized)
-- Show frame (default: true)
-- Enable multi-edit (default: true)
-- Height (fixed)
-- Single column mode
-- Frontend implementation choice
-
-### Common Patterns
-
-1. **Display Referenced Entity Attributes:**
-   - Data Source: Relative Selection (reference attribute)
-   - Layout: Arrange key attributes in custom layout
-   - Edit: Often disabled for referenced data
-
-2. **Custom Form Layout:**
-   - Data Source: Embedding page
-   - Layout: Multi-column with logical groupings
-   - Edit: Enabled for data entry
-
-3. **Read-Only Summary View:**
-   - Data Source: Absolute or relative selection
-   - Layout: Compact, focused attribute display
-   - Edit: Disabled
-   - Frame: Often hidden for seamless integration
-
----
-
-## Research Completion
-
-This research provides comprehensive understanding of:
-- ✅ Widget purpose and core functionality
-- ✅ Use cases and when to use this widget
-- ✅ Configuration options and their purposes
-- ✅ Technical implementation (backend and frontend)
-- ✅ Relationships to other widgets
-- ✅ Code references and key files
-- ✅ Migration and backward compatibility
-
-**Next Steps:** Transform this research into structured specification files:
-- `_meta.json`: Category metadata
-- `_summary.md`: Brief 1-2 sentence description
-- `_overview.md`: Conceptual documentation with use cases
-- `_implementation.md`: Configuration details and workflows
-- Attribute-specific docs as needed