@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,525 @@
+# 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