@cplace/test-mcp-server 1.0.0 → 1.1.0

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

@@ -0,0 +1,420 @@
+# Widget Research: cf.cplace.treeTableWidget
+
+**Research Date:** 2026-01-16
+**Widget ID:** `cf.cplace.treeTableWidget`
+**Repository:** `cplace-utility-widgets`
+**Version:** 25.3.3
+
+---
+
+## 1. Widget Description
+
+The Tree-structure Table widget displays hierarchical page structures in an interactive table format with expandable/collapsible tree nodes.
+
+---
+
+## 2. Purpose & Core Functionality
+
+The `cf.cplace.treeTableWidget` is a concrete implementation of the platform's abstract `TreeTableWidgetDefinition` that provides a ready-to-use widget for displaying hierarchical page relationships in a tree-table view. It combines the benefits of both tree navigation (hierarchical structure) and table views (column-based data display).
+
+### Key Capabilities:
+
+1. **Hierarchical Display**: Shows parent-child relationships between pages in a tree structure
+2. **Table Integration**: Displays page attributes in configurable columns alongside the tree structure
+3. **Interactive Navigation**: Users can expand/collapse tree nodes to navigate through hierarchies
+4. **Context Menu Actions**: Provides right-click context menu with common page operations
+5. **Filtering & Search**: Supports filtering by page types and searching within the tree structure
+
+### Technical Implementation:
+
+- **Backend**: Extends `cf.cplace.platform.frontend.templating.TreeTableWidgetDefinition`
+- **Frontend**: Uses platform's `TreeTableWidgetTemplateSubstitution` (no custom TypeScript)
+- **Data Handling**: Implements `ExtendedTreeSpecificationHandler` for tree data retrieval
+- **Pure Platform Widget**: Leverages 100% platform functionality without custom frontend code
+
+---
+
+## 3. Use Cases
+
+### Primary Use Cases:
+
+1. **Project/Work Breakdown Structures**
+   - Display project hierarchies with tasks, sub-tasks, and deliverables
+   - Show work package breakdowns in a structured format
+   - Navigate through complex project organizations
+
+2. **Organizational Hierarchies**
+   - Visualize organizational structures (departments, teams, roles)
+   - Display reporting relationships
+   - Navigate through organizational units
+
+3. **Document/Content Hierarchies**
+   - Show document folder structures
+   - Display content hierarchies (chapters, sections, sub-sections)
+   - Navigate through knowledge bases
+
+4. **Product/Component Structures**
+   - Display product hierarchies and component breakdowns
+   - Show system architectures and dependencies
+   - Navigate through technical structures
+
+5. **Navigation & Overview Pages**
+   - Create dashboard pages with hierarchical navigation
+   - Provide overview pages showing entire page structures
+   - Serve as entry points to complex information architectures
+
+### When to Use This Widget:
+
+- **Use when**: You need to display parent-child page relationships with associated data columns
+- **Use when**: Users need to navigate through multi-level hierarchies efficiently
+- **Use when**: You want to combine tree navigation with tabular data display
+- **Use when**: You need quick access to context menu actions on hierarchical items
+
+### When NOT to Use This Widget:
+
+- **Avoid when**: You only need a simple list without hierarchy (use Table widget instead)
+- **Avoid when**: Your data doesn't have parent-child relationships (use regular Table widget)
+- **Avoid when**: You need complex custom interactions (may need custom widget implementation)
+
+---
+
+## 4. Configuration Concepts
+
+### Main Configuration Options:
+
+The widget uses the platform's standard tree table configuration inherited from `BASE_TREE_TABLE`:
+
+#### 4.1 Core Settings
+
+| Configuration | Type | Description | Required |
+|--------------|------|-------------|----------|
+| **Localized Title** | LocalizedString | Display name shown in widget header | Optional |
+| **Root Node** | PageReference | Starting point for tree hierarchy (uses embedded page if not specified) | Optional |
+| **Default Depth** | Number | How many levels to expand by default | Optional |
+
+#### 4.2 Data & Display
+
+| Configuration | Type | Description | Required |
+|--------------|------|-------------|----------|
+| **Attributes** | MultiString | Defines which attributes to display as columns in the table | Yes (at least 1) |
+| **Columns** | String | Column configuration (width, sorting, visibility) | Optional |
+| **Search** | String | Search and filter configuration in JSON format | Yes |
+| **Filters** | String | Additional filter criteria for displayed items | Optional |
+
+### Configuration Modes:
+
+1. **Basic Hierarchy Mode**
+   - Root node = embedded page (widget's container page)
+   - Shows children of the current page
+   - Default depth controls initial expansion
+
+2. **Custom Root Mode**
+   - Specify a different page as root node
+   - Shows hierarchy starting from specified page
+   - Useful for cross-page hierarchy views
+
+3. **Filtered View Mode**
+   - Use search filters to limit displayed page types
+   - Apply attribute-based filters
+   - Create focused views of specific hierarchies
+
+### Search Configuration Details:
+
+The search configuration uses JSON format (from TestSetupHandler.java:60-61):
+
+```json
+{
+  "filters": [
+    {
+      "types": ["default.page"]
+    }
+  ]
+}
+```
+
+### Attributes Configuration Details:
+
+The attributes configuration defines the parent-child relationship (from TestSetupHandler.java:63-65):
+
+```json
+{
+  "parentType": "default.page",
+  "incomingType": "default.page",
+  "name": "default.parent"
+}
+```
+
+This specifies:
+- **parentType**: The type of parent pages
+- **incomingType**: The type of child pages
+- **name**: The attribute name that defines the parent relationship
+
+---
+
+## 5. Context & Relationships
+
+### Relationship to Platform:
+
+- **Extends**: `cf.cplace.platform.frontend.templating.TreeTableWidgetDefinition`
+- **Uses**: `TreeTableWidgetTemplateSubstitution` for rendering
+- **Implements**: `ExtendedTreeSpecificationHandler` for data handling
+- **Dependency**: Only depends on `cf.cplace.platform` (version 25.3.80+)
+
+### Relationship to Other Widgets:
+
+- **Similar to**: Platform's base tree table widget (`cf.platform.treeTable`)
+- **Difference**: Provides a concrete, ready-to-use implementation vs. abstract base class
+- **Complements**: Table widgets (when hierarchy is needed), Tree widgets (when tabular data is needed)
+
+### Widget Family:
+
+This widget is part of the `cplace-utility-widgets` repository, which provides ready-to-use implementations of platform capabilities without requiring custom frontend code.
+
+---
+
+## 6. Context Menu Actions
+
+The widget provides rich context menu functionality when right-clicking on tree nodes:
+
+### Available Actions:
+
+1. **New Subpage** - Create a child page under the selected node
+2. **Open in New Tab** - Open the selected page in a new browser tab
+3. **Expand All Children** - Recursively expand all child nodes
+4. **Copy** - Copy the selected page
+5. **Move** - Move the page to a different parent
+6. **Delete** - Delete the selected page
+
+### Implementation:
+
+- Context menu is handled by `GetContextMenuActionsHandler`
+- Actions are provided by `ContextMenuActionsProvider` extending `PagePresentation`
+- The "Expand All Children" action is widget-specific (TreeSpecificationHandler.java:22-24)
+
+---
+
+## 7. Technical Architecture
+
+### Backend Components:
+
+```
+TreeTableWidgetDefinition.java
+├── Extends: cf.cplace.platform.frontend.templating.TreeTableWidgetDefinition
+├── Widget Kind: "cf.cplace.treeTableWidget"
+├── Configuration Type: TreeTableWidgetWidgetTypes.CONFIGURATION.TYPE
+└── Returns: TreeTableWidgetTemplateSubstitution
+
+TreeSpecificationHandler.java
+├── Extends: ExtendedTreeSpecificationHandler
+├── Enables: showActions() = true
+└── Context Menu: GetContextMenuActionsHandler
+
+GetContextMenuActionsHandler.java
+├── Type: JSON Handler
+├── Input: Selected page UID
+└── Output: Available context menu actions
+
+ContextMenuActionsProvider.java
+├── Extends: PagePresentation
+└── Provides: EXPAND_ALL_CHILDREN action + standard page actions
+```
+
+### Frontend Components:
+
+**None** - This widget uses 100% platform rendering:
+- `pluginDescriptor.json` specifies `"hasTypeScriptAssets": false`
+- Rendering handled by platform's `TreeTableWidgetTemplateSubstitution`
+- No custom TypeScript/JavaScript code required
+
+### Configuration Type Definition:
+
+Located in `TreeTableWidgetWidgetTypes.java`, the configuration type inherits all fields from `BASE_TREE_TABLE`:
+
+- **LOCALIZED_TITLE** - Copy of `BASE_MIXIN.TITLE`
+- **COLUMNS** - Copy of `BASE_TREE_TABLE.COLUMNS`
+- **SEARCH** - Copy of `BASE_TREE_TABLE.SEARCH` (read-only, hidden in attributes widget)
+- **DEFAULT_DEPTH** - Copy of `BASE_TREE_TABLE.DEFAULT_DEPTH`
+- **FILTERS** - Copy of `BASE_TREE_TABLE.FILTERS`
+- **ATTRIBUTES** - Copy of `BASE_TREE_TABLE.ATTRIBUTES`
+- **ROOT_NODE** - Copy of `BASE_TREE_TABLE.ROOT_NODE`
+
+---
+
+## 8. Internationalization
+
+The widget provides localized names and labels:
+
+### English (messages_en.properties):
+- **Widget Name**: "Tree-structure Table"
+- **Description**: "Displays a tree structure in a table."
+- **Expand Action**: "Expand all children"
+
+### German (messages_de.properties):
+- **Widget Name**: "Baumstruktur-Tabelle"
+- **Description**: "Zeigt eine Baumstruktur in einer Tabelle an."
+- **Expand Action**: "Alle Kinder ausklappen"
+
+---
+
+## 9. Example Usage (from Tests)
+
+The test setup creates a simple tree table widget showing page hierarchies:
+
+```java
+// Create widget with configuration
+WidgetWithContent.newWidgetWithConfigurationAndType(
+    CustomSerializable.jsonBuilder()
+        // Filter to show only default pages
+        .put("cf.cplace.platform.search",
+            StringValue.valueOf("{\"filters\":[{\"types\":[\"default.page\"]}]}"))
+
+        // Define parent-child relationship using default.parent attribute
+        .put("cf.cplace.platform.attributes",
+            StringValue.valueOf(
+                "{\"parentType\":\"default.page\"," +
+                "\"incomingType\":\"default.page\"," +
+                "\"name\":\"default.parent\"}"))
+
+        // Localized title
+        .put("title",
+            LocalizedStringValue.valueOf("{\"de\":\"Baumtabelle\",\"en\":\"TreeTable\"}"))
+        .toJson(),
+    "cf.cplace.treeTableWidget"
+)
+```
+
+This creates a widget that:
+1. Shows only pages of type `default.page`
+2. Uses the `default.parent` attribute to build the tree hierarchy
+3. Displays with title "TreeTable" / "Baumtabelle"
+4. Starts from the embedded page (root page)
+
+---
+
+## 10. Prerequisites & Dependencies
+
+### Plugin Dependencies:
+- **cf.cplace.platform** (version 25.3.80 or higher)
+
+### Data Model Requirements:
+- Pages must have a parent-child relationship attribute (e.g., `default.parent`)
+- Parent attribute must be properly configured as a page reference
+- Page types must support hierarchical relationships
+
+### User Permissions:
+- Read access to pages in the hierarchy
+- Context menu actions require appropriate permissions (e.g., create, delete, move)
+
+### No Frontend Dependencies:
+- No TypeScript/JavaScript required
+- No custom frontend assets
+- Uses only platform rendering capabilities
+
+---
+
+## 11. Key Differences from Platform Base Widget
+
+While this widget extends the platform's base `TreeTableWidgetDefinition`, it provides:
+
+1. **Concrete Implementation**: Ready-to-use without needing to implement abstract methods
+2. **Context Menu**: Pre-configured context menu with standard actions + "Expand All Children"
+3. **Default Configuration**: Sensible defaults for common use cases
+4. **Simplified Setup**: No need to create custom handlers or templates
+
+The platform's base widget is abstract and requires:
+- Implementation of `getTreeSpec()` method
+- Custom tree specification handler
+- Custom configuration type definition
+
+This utility widget provides all of that out-of-the-box for standard page hierarchies.
+
+---
+
+## 12. Source Code Locations
+
+### Repository Path:
+```
+cplace-utility-widgets/cf.cplace.treeTableWidget/
+```
+
+### Key Files:
+
+**Java Classes:**
+```
+src/main/java/cf/cplace/treeTableWidget/
+├── TreeTableWidgetApp.java
+├── TreeTableWidgetPlugin.java
+├── TreeTableWidgetWidgetTypes.java
+├── script/
+│   └── TreeTableWidgetDefinition.java
+└── handler/
+    ├── TreeSpecificationHandler.java
+    ├── GetContextMenuActionsHandler.java
+    ├── ContextMenuActionsProvider.java
+    └── test/
+        └── TestSetupHandler.java
+```
+
+**Resources:**
+```
+src/main/resources/
+├── META-INF/cf.cplace.treeTableWidget/
+│   └── pluginDescriptor.json
+└── cf/cplace/treeTableWidget/
+    ├── messages_en.properties
+    └── messages_de.properties
+```
+
+**Definition Class:**
+`/Users/thomasbuechner/dev/repos/cplace-utility-widgets/cf.cplace.treeTableWidget/src/main/java/cf/cplace/treeTableWidget/script/TreeTableWidgetDefinition.java`
+
+---
+
+## 13. Research Notes
+
+### Design Decisions:
+
+1. **No Custom Frontend**: Intentionally uses platform rendering to reduce maintenance burden
+2. **Extends Platform Base**: Leverages proven platform infrastructure
+3. **Standard Configuration**: Uses platform's BASE_TREE_TABLE configuration pattern
+4. **Context Menu Integration**: Adds context menu support not present in all tree widgets
+
+### Limitations Identified:
+
+1. **Page-Only**: Designed specifically for page hierarchies (not custom entities)
+2. **Single Hierarchy**: Uses one parent attribute at a time (no multiple relationship types)
+3. **Platform Rendering**: Limited to platform's rendering capabilities (can't customize without TypeScript)
+4. **Error Handling**: Throws `TreeUnconstructableException` if embedded in a TypeDefinition page
+
+### Best Practices:
+
+1. Always define at least one attribute in the attributes configuration
+2. Use appropriate search filters to limit displayed page types
+3. Set reasonable default depth to avoid performance issues with large hierarchies
+4. Ensure parent-child relationship attribute exists and is properly configured
+5. Test context menu permissions for expected user roles
+
+---
+
+## 14. Summary
+
+The `cf.cplace.treeTableWidget` is a **pure platform-based implementation** of a tree-table widget that provides an easy way to display hierarchical page structures without requiring custom frontend code. It's ideal for displaying organizational structures, project breakdowns, document hierarchies, and any other parent-child page relationships in an interactive, expandable tree format with tabular data display.
+
+### Quick Facts:
+
+- ✅ **Ready to use** - No custom development required
+- ✅ **Pure backend** - No TypeScript/frontend code
+- ✅ **Context menu** - Rich interaction capabilities
+- ✅ **Configurable** - Flexible display and filtering options
+- ✅ **Localized** - English and German translations included
+- ✅ **Platform-based** - Leverages core platform capabilities
+- ⚠️ **Page-only** - Works with page hierarchies (not custom entities)
+- ⚠️ **Platform rendering** - Limited to platform's display capabilities
+
+### When to Choose This Widget:
+
+Choose `cf.cplace.treeTableWidget` when you need a simple, reliable way to display page hierarchies in a tree-table format without the complexity of custom frontend development. It's perfect for standard page hierarchies where platform rendering is sufficient and context menu actions are valuable.
+
+---
+
+**End of Research Document**