@cplace/test-mcp-server 1.0.0 → 1.1.0

package/dist/widget-specifications/WIDGET-TAGGING-SCHEME.md

@@ -0,0 +1,217 @@
+# Widget Tagging Scheme for cplace
+
+This document defines a multi-dimensional tagging system for cplace widgets. Tags help AI assistants identify appropriate widgets based on user needs and requirements.
+
+---
+
+## Overview
+
+- **Total Tags**: ~30 tags across 5 dimensions
+- **Purpose**: Enable AI-driven widget recommendations based on user intent
+- **Principle**: Widgets receive multiple tags (multi-dimensional) rather than single categories
+
+---
+
+## Tag Dimensions
+
+### 1. Data/Content Type
+*What the widget works with*
+
+| Tag | Description | Example Use Case |
+|-----|-------------|------------------|
+| `attributes` | Works with page attributes/properties | Displaying project status, budget, owner |
+| `files` | Handles file attachments/documents | Managing project deliverables |
+| `rich-text` | Formatted text content (HTML, Wiki) | Documentation, descriptions |
+| `media` | Images, video, visual content | Product images, preview thumbnails |
+| `comments` | Discussion threads, feedback | Team communication on pages |
+| `references` | Page relationships, links between pages | Dependencies, incoming links |
+| `metadata` | System info (versions, timestamps, tags) | Audit trails, version history |
+| `time-series` | Date-based, time-phased data | Schedules, resource allocations |
+
+---
+
+### 2. Display Format
+*How data is presented visually*
+
+| Tag | Description | Example Use Case |
+|-----|-------------|------------------|
+| `chart` | Graphical visualization (bar, pie, line) | KPI dashboards, status distribution |
+| `table` | Tabular rows and columns | Project lists, issue trackers |
+| `list` | Simple sequential display | Navigation menus, search results |
+| `board` | Card-based layout (Kanban-style) | Task management, workflow stages |
+| `timeline` | Gantt, roadmap, schedule visualization | Project schedules, product roadmaps |
+| `tree` | Hierarchical/nested structure | Work breakdown, org charts |
+| `matrix` | Two-dimensional grid | Responsibility matrices, risk matrices |
+| `form` | Input fields layout | Data entry, attribute editing |
+| `gallery` | Visual thumbnail grid | Document galleries, image collections |
+
+---
+
+### 3. Interaction Capabilities
+*What users can do with the widget*
+
+| Tag | Description | Example Use Case |
+|-----|-------------|------------------|
+| `read-only` | Display only, no editing | Executive dashboards, reports |
+| `inline-edit` | Edit values in place | Quick updates, status changes |
+| `filterable` | User can filter displayed data | Finding specific items |
+| `sortable` | User can reorder/sort data | Prioritization, ranking |
+| `searchable` | Content driven by search queries | Dynamic lists, filtered views |
+| `drag-drop` | Supports drag and drop interaction | Kanban cards, file uploads |
+| `selectable` | Items can be selected (for master-detail) | Click-to-show-details patterns |
+
+---
+
+### 4. Purpose/Context
+*Why you'd use this widget*
+
+| Tag | Description | Example Use Case |
+|-----|-------------|------------------|
+| `dashboard` | Aggregated overview, KPIs | Management cockpits |
+| `detail-view` | Single page/item details | Project detail pages |
+| `navigation` | Browsing, finding pages | Workspace navigation |
+| `collaboration` | Team communication | Comments, shared editing |
+| `reporting` | Export, report generation | Status reports, presentations |
+| `scheduling` | Time/resource planning | Gantt charts, resource allocation |
+
+---
+
+### 5. Technical Characteristics
+*Implementation considerations*
+
+| Tag | Description | Example Use Case |
+|-----|-------------|------------------|
+| `low-code` | Requires cplaceJS scripting | Custom visualizations |
+| `connected` | Links to other widgets (master-detail) | Table-to-detail patterns |
+| `container` | Holds other widgets/layouts | Tab containers, layout organization |
+
+---
+
+## Complete Widget Tag Mapping
+
+### Platform Widgets (cf.cplace.platform / cf.platform)
+
+| Widget ID | Widget Name | Tags |
+|-----------|-------------|------|
+| `cf.platform.attributes` | Attributes | `attributes`, `form`, `detail-view`, `inline-edit` |
+| `cf.platform.attributeHistory` | Attribute Versions | `metadata`, `table`, `read-only`, `detail-view` |
+| `cf.platform.comments` | Comments | `comments`, `collaboration`, `inline-edit`, `detail-view` |
+| `cf.platform.connectedBarChart` | Bar Chart | `chart`, `attributes`, `searchable`, `filterable`, `dashboard` |
+| `cf.platform.connectedMatrix` | Matrix | `matrix`, `attributes`, `searchable`, `filterable`, `dashboard` |
+| `cf.platform.connectedPieChart` | Pie Chart | `chart`, `attributes`, `searchable`, `filterable`, `dashboard` |
+| `cf.platform.connectedTableFilter` | Filter Configuration | `attributes`, `filterable`, `connected` |
+| `cf.platform.customRichStringAttribute` | Richstring Attribute | `rich-text`, `attributes`, `detail-view`, `inline-edit` |
+| `cf.platform.embeddedSearchAsList` | List | `list`, `searchable`, `navigation`, `selectable` |
+| `cf.platform.embeddedSearchAsTable` | Table | `table`, `searchable`, `filterable`, `sortable`, `selectable`, `navigation` |
+| `cf.platform.files` | Files | `files`, `media`, `inline-edit`, `drag-drop`, `detail-view` |
+| `cf.platform.iframe` | Inline Frame | `container`, `read-only` |
+| `cf.platform.incomingLinks` | Incoming Links | `references`, `list`, `navigation`, `read-only` |
+| `cf.platform.incomingReferences` | Incoming References | `references`, `list`, `navigation`, `read-only` |
+| `cf.platform.modificationInfo` | Version Info | `metadata`, `read-only`, `detail-view` |
+| `cf.platform.richString` | Text | `rich-text`, `inline-edit`, `detail-view` |
+| `cf.platform.tags` | Tags | `metadata`, `inline-edit`, `filterable` |
+| `cf.platform.wiki` | Wiki | `rich-text`, `collaboration`, `inline-edit`, `detail-view` |
+
+### Extended Platform Widgets
+
+| Widget ID | Widget Name | Tags |
+|-----------|-------------|------|
+| `cf.cplace.platform.attributesGroup` | Grouped Attributes of a Page | `attributes`, `form`, `detail-view`, `inline-edit` |
+| `cf.cplace.platform.connectedAttributesGroup` | Grouped Attributes of a Table | `attributes`, `form`, `detail-view`, `connected`, `inline-edit` |
+| `cf.cplace.platform.dynamicIframe` | Dynamic Inline Frame | `container`, `connected`, `read-only` |
+| `cf.cplace.platform.tableWidget` | New Table (Beta) | `table`, `searchable`, `filterable`, `sortable`, `selectable`, `inline-edit` |
+
+### Content & Media Widgets
+
+| Widget ID | Widget Name | Tags |
+|-----------|-------------|------|
+| `cf.cplace.demoWidgets.demoRichString` | Text without widget frame | `rich-text`, `container`, `low-code` |
+| `cf.cplace.dragAndDropImageView.widget` | Image | `media`, `gallery`, `drag-drop`, `detail-view` |
+| `cf.cplace.dragAndDropImageView.imageWithTextWidget` | Image with text | `media`, `rich-text`, `detail-view` |
+| `cf.cplace.dragAndDropImageView.imageWithTextAndListWidget` | Image with text and list | `media`, `rich-text`, `list`, `detail-view` |
+| `cf.cplace.pdfPreview.widget` | PDF Preview | `files`, `media`, `read-only`, `detail-view` |
+| `cf.cplace.videoWidget` | Video | `media`, `read-only`, `detail-view` |
+| `msg.scripts.imagegallery.basic` | Document Gallery | `files`, `gallery`, `media`, `navigation` |
+
+### Visualization Widgets
+
+| Widget ID | Widget Name | Tags |
+|-----------|-------------|------|
+| `cf.cplace.visualizations.scriptingHighcharts` | cplaceJS Highcharts | `chart`, `low-code`, `dashboard`, `filterable` |
+| `cf.cplace.visualizations.scriptingLineChart` | cplaceJS Line Chart | `chart`, `time-series`, `low-code`, `dashboard` |
+| `cf.cplace.visualizations.tupleLineChart` | Tuple Line Chart | `chart`, `time-series`, `dashboard` |
+
+### Layout & Navigation Widgets
+
+| Widget ID | Widget Name | Tags |
+|-----------|-------------|------|
+| `cf.cplace.layoutTabsWidget.widget` | Alternative Layouts as Tabs | `container`, `navigation` |
+| `cf.cplace.pageViewHeadline.widget` | Simple Headline | `rich-text`, `read-only`, `detail-view` |
+| `cf.cplace.tableDetailViewWidget.widget` | Page Details | `attributes`, `detail-view`, `connected`, `read-only` |
+
+### Input & Action Widgets
+
+| Widget ID | Widget Name | Tags |
+|-----------|-------------|------|
+| `cf.cplace.lowCodeWidgets.lowCodeButton` | Low-Code Button | `low-code`, `inline-edit` |
+| `cf.cplace.simpleForm.widget` | Creation Form | `form`, `attributes`, `inline-edit` |
+| `cf.cplace.dynamicCodeBlockWidget.dynamicCodeBlockWidget` | Dynamic Code Block | `low-code`, `rich-text` |
+| `cf.cplace.tuplesWidget.widget` | Tuple | `attributes`, `table`, `time-series`, `inline-edit` |
+
+### Plugin Widgets (require specific apps)
+
+| Widget ID | Widget Name | App | Tags |
+|-----------|-------------|-----|------|
+| `cf.cplace.cboard.main.board` | Kanban Board | cBoard | `board`, `drag-drop`, `inline-edit`, `collaboration`, `selectable` |
+| `cf.cplace.resourceManagement.resourcePlannerDefinition` | Resource Planner | Resource Management | `table`, `tree`, `time-series`, `scheduling`, `inline-edit`, `dashboard` |
+| `cf.projektplanung.multiGantt` | Multi Gantt | Projektplanung | `timeline`, `tree`, `time-series`, `scheduling`, `dashboard`, `connected` |
+| `cf.projektplanung.scheduleTreeTable` | Schedule Tree Table | Projektplanung | `table`, `tree`, `time-series`, `scheduling`, `inline-edit` |
+| `cf.projektplanung.singleGanttLink` | Single Gantt Link | Projektplanung | `timeline`, `time-series`, `scheduling`, `navigation`, `read-only` |
+| `cf.cplace.cplaceReportGeneration.generateReportWidget` | Report Creation | Report Generation | `reporting`, `files` |
+| `cf.cplace.formsWizard.startWizardWidget` | Start Wizard | Forms Wizard | `form`, `navigation`, `inline-edit` |
+| `cf.cplace.pptexport.pgPreviewWidget` | Presentation Preview | Presentation Graphic | `timeline`, `reporting`, `read-only` |
+
+---
+
+## Usage Guidelines for AI Widget Selection
+
+### Matching User Intent to Tags
+
+| User Says... | Look for Tags |
+|--------------|---------------|
+| "I need a chart/graph" | `chart` |
+| "Show me a table/list of..." | `table`, `list` |
+| "I want to see the schedule/timeline" | `timeline`, `scheduling` |
+| "Where can users edit/update..." | `inline-edit` |
+| "Display details of a single item" | `detail-view` |
+| "Overview/dashboard/summary" | `dashboard` |
+| "Kanban/board/cards" | `board` |
+| "Upload/attach files" | `files`, `drag-drop` |
+| "Team discussion/comments" | `comments`, `collaboration` |
+| "Filter/search for..." | `filterable`, `searchable` |
+| "Hierarchical/tree structure" | `tree` |
+| "Export/report" | `reporting` |
+| "Custom visualization" | `low-code` |
+| "Click on row to show details" | `selectable`, `connected` |
+
+### Tag Combinations for Common Patterns
+
+| Pattern | Recommended Tag Combination |
+|---------|----------------------------|
+| Master-Detail | `selectable` + `connected` |
+| Executive Dashboard | `chart` + `dashboard` + `read-only` |
+| Project Status Page | `attributes` + `detail-view` + `inline-edit` |
+| Task Management | `board` + `drag-drop` + `collaboration` |
+| Schedule Overview | `timeline` + `scheduling` + `dashboard` |
+| Data Entry Form | `form` + `inline-edit` + `attributes` |
+| Document Management | `files` + `gallery` + `drag-drop` |
+
+---
+
+## Notes
+
+- Widgets may have additional tags based on specific configuration
+- `low-code` tag indicates advanced customization capabilities
+- `connected` widgets require pairing with other widgets (typically Table)
+- Plugin widgets require their respective apps to be installed
+- Some widgets support both read and edit modes (tagged with `inline-edit`)

package/dist/widget-specifications/_research_from_ga_products/.claude-settings.local.json

@@ -0,0 +1,48 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(bash -c 'cd /Users/thomasbuechner/dev/repos && for repo in cplace-2lforge-changes cplace-2lforge-comments cplace-2lforge-curves cplace-2lforge-messages cplace-2lforge-toolbox cplace-2lforge-toolbar cplace-2lforge-trends cplace-analytics cplace-api-common cplace-arorian-codebeamer cplace-attribute-dependencies cplace-authentication cplace-board cplace-citizen-ai cplace-ctts cplace-dataciders-portfolio-management cplace-ecf cplace-forms-wizard cplace-generic-interface cplace-gtv cplace-jira cplace-loomeo cplace-lowcode-job-scheduler cplace-mcp-endpoints cplace-office-reports cplace-paw cplace-project-planning cplace-resource-management cplace-rest-client cplace-rest cplace-scim2 cplace-soap cplace-time-bounded-values cplace-utility-apps cplace-utility-widgets cplace-vdm cplace-workflow; do if [ -d \"\"$repo\"\" ]; then echo \"\"=== $repo ===\"\"; ls \"\"$repo\"\" 2>/dev/null | grep -E \"\"^\\(cf\\\\\\\\.|com\\\\\\\\.|de\\\\\\\\.|tt\\\\\\\\.\\)\"\" || echo \"\"\\(no plugins\\)\"\"; else echo \"\"=== $repo === \\(not found\\)\"\"; fi; done')"
+    ],
+    "additionalDirectories": [
+      "/Users/thomasbuechner/dev/repos/cplace",
+      "/Users/thomasbuechner/dev/repos/cplace-2lforge-changes",
+      "/Users/thomasbuechner/dev/repos/cplace-2lforge-comments",
+      "/Users/thomasbuechner/dev/repos/cplace-2lforge-curves",
+      "/Users/thomasbuechner/dev/repos/cplace-2lforge-messages",
+      "/Users/thomasbuechner/dev/repos/cplace-2lforge-toolbox",
+      "/Users/thomasbuechner/dev/repos/cplace-2lforge-toolbar",
+      "/Users/thomasbuechner/dev/repos/cplace-2lforge-trends",
+      "/Users/thomasbuechner/dev/repos/cplace-analytics",
+      "/Users/thomasbuechner/dev/repos/cplace-api-common",
+      "/Users/thomasbuechner/dev/repos/cplace-arorian-codebeamer",
+      "/Users/thomasbuechner/dev/repos/cplace-attribute-dependencies",
+      "/Users/thomasbuechner/dev/repos/cplace-authentication",
+      "/Users/thomasbuechner/dev/repos/cplace-board",
+      "/Users/thomasbuechner/dev/repos/cplace-citizen-ai",
+      "/Users/thomasbuechner/dev/repos/cplace-ctts",
+      "/Users/thomasbuechner/dev/repos/cplace-dataciders-portfolio-management",
+      "/Users/thomasbuechner/dev/repos/cplace-ecf",
+      "/Users/thomasbuechner/dev/repos/cplace-forms-wizard",
+      "/Users/thomasbuechner/dev/repos/cplace-generic-interface",
+      "/Users/thomasbuechner/dev/repos/cplace-gtv",
+      "/Users/thomasbuechner/dev/repos/cplace-jira",
+      "/Users/thomasbuechner/dev/repos/cplace-loomeo",
+      "/Users/thomasbuechner/dev/repos/cplace-lowcode-job-scheduler",
+      "/Users/thomasbuechner/dev/repos/cplace-mcp-endpoints",
+      "/Users/thomasbuechner/dev/repos/cplace-office-reports",
+      "/Users/thomasbuechner/dev/repos/cplace-paw",
+      "/Users/thomasbuechner/dev/repos/cplace-project-planning",
+      "/Users/thomasbuechner/dev/repos/cplace-resource-management",
+      "/Users/thomasbuechner/dev/repos/cplace-rest",
+      "/Users/thomasbuechner/dev/repos/cplace-rest-client",
+      "/Users/thomasbuechner/dev/repos/cplace-scim2",
+      "/Users/thomasbuechner/dev/repos/cplace-soap",
+      "/Users/thomasbuechner/dev/repos/cplace-time-bounded-values",
+      "/Users/thomasbuechner/dev/repos/cplace-utility-apps",
+      "/Users/thomasbuechner/dev/repos/cplace-utility-widgets",
+      "/Users/thomasbuechner/dev/repos/cplace-vdm",
+      "/Users/thomasbuechner/dev/repos/cplace-workflow",
+      "/Users/thomasbuechner/dev/tmp/cplace-mcp-server"
+    ]
+  }
+}

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-api-common-config-metadata-SyncMetadataTable/research.md

@@ -0,0 +1,168 @@
+# SyncMetadataTable Widget Research
+
+## Widget Overview
+
+- **Widget ID:** `cf.cplace.api.common.config.metadata.SyncMetadataTable`
+- **Display Name:** "Synchronization status table"
+- **Repository:** `cplace-ecf`
+- **Definition Class:** `cf.cplace.ecf/src/main/java/cf/cplace/ecf/sync/metadata/extension/widget/SyncMetadataTableWidgetDefinition.java`
+- **Icon:** `cf-attribute-selection`
+
+## Short Description
+
+The SyncMetadataTable widget displays a table of all synchronization metadata entries associated with a specific synchronization configuration, showing the relationship and synchronization status between internal cplace entities and external system entities.
+
+## Purpose and Core Functionality
+
+The SyncMetadataTable widget is part of the Enterprise Connectivity Framework (ECF) and serves as the primary interface for monitoring synchronization status between cplace and external systems. It displays synchronization metadata entries that track:
+
+1. **Entity Relationships:** Links between internal cplace entities and their corresponding external system entities
+2. **Synchronization State:** Current status of each synchronized entity (NEW, MODIFIED, SYNCED, ORPHANED, DELETED)
+3. **Sync History:** Timestamps of last synchronization attempts and successful synchronizations
+4. **Error Information:** Error messages from failed synchronization attempts
+
+### Key Data Displayed
+
+The widget displays the following columns (varies by sync mode):
+
+| Column | Description |
+|--------|-------------|
+| Internal Entity | Reference to the cplace page being synchronized |
+| External Entity | Name of the corresponding entity in the external system |
+| Internal State | Synchronization state of the internal entity (OUTBOUND/BIDIRECTIONAL modes) |
+| External State | Synchronization state of the external entity (INBOUND/BIDIRECTIONAL modes) |
+| Last Synchronization Attempt | Timestamp of the most recent sync attempt |
+| Last Successful Synchronization | Timestamp of the last successful sync |
+| Last Outbound Error | Error message from outbound sync failures (OUTBOUND/BIDIRECTIONAL) |
+| Last Inbound Error | Error message from inbound sync failures (INBOUND/BIDIRECTIONAL) |
+
+## Use Cases
+
+### 1. Monitoring Synchronization Status
+Administrators use this widget to monitor the overall health of synchronizations between cplace and external systems. They can quickly identify:
+- Entities pending synchronization (state: NEW or MODIFIED)
+- Successfully synchronized entities (state: SYNCED)
+- Problematic entities with sync failures (via error message columns)
+- Orphaned entities no longer in sync scope (state: ORPHANED)
+
+### 2. Troubleshooting Sync Failures
+When synchronization issues occur, this widget provides detailed error messages and timestamps to help diagnose problems. Each row shows:
+- Which specific entity failed
+- When the failure occurred
+- The error message explaining the failure reason
+
+### 3. Managing Entity Assignments
+The widget includes an action to remove pages from synchronization ("Unassign pages"). This allows administrators to:
+- Remove entities that should no longer be synchronized
+- Clean up orphaned metadata entries
+- Manage the scope of synchronization configurations
+
+### 4. Validating Sync Configuration
+Before enabling a sync configuration, administrators can verify:
+- Which entities will be synchronized
+- The expected sync direction
+- Initial state of entities
+
+## Configuration Concepts
+
+### Widget Configuration Options
+
+The widget has minimal configuration:
+
+| Option | Type | Description |
+|--------|------|-------------|
+| HEIGHT | Number | Widget height (inherited from base mixin) |
+
+### Placement Restrictions
+
+The widget can **only** be embedded on ECF Sync Configuration pages. Attempting to add it to other page types will result in an error:
+> "SyncMetadataTableWidgetDefinition can only be used for Enterprise Connectivity synchronization configuration pages. Make sure that the corresponding Connector App is installed in this workspace"
+
+### Sync Mode Awareness
+
+The widget automatically adapts its displayed columns based on the sync configuration's mode:
+
+- **OUTBOUND:** Shows Internal State, Last Outbound Error
+- **INBOUND:** Shows External State, Last Inbound Error
+- **BIDIRECTIONAL:** Shows both Internal/External States and both error columns
+
+## Context and Related Widgets
+
+### ECF Widget Ecosystem
+
+The SyncMetadataTable is part of a suite of ECF widgets:
+
+1. **SyncMetadataTable** (this widget) - Displays sync status for a configuration
+2. **AttributeMappingTableWidgetDefinition** - Shows attribute mappings between internal and external types
+3. **ConnectorSyncConfigsTableWidgetDefinition** - Lists all sync configurations for a connector
+4. **ServerConnectionTableWidgetDefinition** - Manages server connections
+5. **CleanupConfigTableWidgetDefinition** - Manages cleanup job configurations
+
+### Default Layout Integration
+
+The widget is included in the default layout for ECF sync configuration pages as part of a tabbed interface:
+
+- **Configuration Tab:** Attributes widget + Attribute Mapping Table
+- **Synchronization Tab:** SyncMetadataTable widget (this widget)
+
+This tab structure is automatically applied to all ECF sync configuration types via `SyncConfigurationWidgetDefinitions.applyAlternativeLayouts()`.
+
+### Prerequisites and Dependencies
+
+To use this widget:
+1. The ECF plugin (`cf.cplace.ecf`) must be installed
+2. A Connector App must be deployed in the workspace
+3. The widget must be placed on a page of type `cf.cplace.ecf.syncConfiguration` or its subtypes
+
+### Underlying Data Model
+
+The widget reads from the `ExtSyncMetadata` built-in entity type, which is a non-custom persistent entity that stores:
+- Sync configuration reference
+- Internal entity reference (cplace page)
+- External entity identifiers (namespace, type, ID, name)
+- Synchronization states (internal and external)
+- Timestamps (last attempt, last success, last modification)
+- Error messages (inbound and outbound)
+
+### Table Actions
+
+The widget extends the standard table actions with:
+- **Remove from synchronization:** Allows bulk removal of selected entities from the sync configuration (removes the metadata entry, effectively unassigning the entity)
+
+Export actions are disabled because the `ExtSyncMetadata` built-in type doesn't support export jobs.
+
+## Technical Details
+
+### Class Hierarchy
+
+```
+GenericSearchAsTableWidgetDefinition
+  └── AbstractSyncConfigTableWidgetDefinition
+        └── SyncMetadataTableWidgetDefinition
+```
+
+### Key Implementation Classes
+
+- `SyncMetadataTableWidgetDefinition` - Widget definition and registration
+- `SyncMetadataTableSpecificationHandler` - Table data source and column configuration
+- `AbstractSyncConfigTableWidgetDefinition` - Base class with embedding validation
+- `ExtSyncMetadata` - Underlying data entity
+- `SyncMetadataRepository` - Data access interface
+- `SyncUnassignmentActionsExtension` - Custom table actions
+
+### Search Behavior
+
+The widget constructs its table search using:
+```java
+EcfPlugin.INSTANCE().getMetadataRepository()
+    .createSearch()
+    .syncConfiguration((CustomEntity) entity)
+    .build()
+    .getSearch();
+```
+
+This retrieves all metadata entries referencing the embedding sync configuration entity.
+
+### Link Display Behavior
+
+The widget sets `hideLinks()` to return `true`, meaning entity names are displayed as plain text rather than links. This is because metadata entries don't have their own page/presentation view - the data is only meaningful in the context of the table.

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

@@ -0,0 +1,125 @@
+# Breadcrumbs Widget Research
+
+**Widget ID:** `cf.cplace.breadcrumbs.breadcrumbsWidget`
+**Repository:** `cplace-paw`
+**Plugin:** `cf.cplace.breadcrumbs`
+
+## Widget Description
+
+The Breadcrumbs Widget displays a hierarchical navigation path from the current page to the workspace home page. It provides users with visual context about their location within the page hierarchy and enables quick navigation to parent pages.
+
+## Purpose
+
+This widget shows the hierarchical path to the home page of a workspace, helping users understand their current position within the page structure and navigate between hierarchical levels. The breadcrumbs are displayed as clickable links with a distinctive arrow-style visual design.
+
+## Core Functionality
+
+Based on the widget definition class (`BreadcrumbsWidgetDefinition.java`), the widget:
+
+1. **Retrieves Page Hierarchy**: Uses `Page.getPageByUid()` and `getPathToRoot()` to obtain the hierarchical path from the current page to the workspace root (BreadcrumbsWidgetDefinition.java:71-72)
+
+2. **Displays Path in Reverse**: Reverses the path list so it displays from root to current page (BreadcrumbsWidgetDefinition.java:73)
+
+3. **Renders Without Frame**: Configured with `showFrame() = false` and `isNoPadding() = true` for seamless integration into page layouts (BreadcrumbsWidgetDefinition.java:57-62)
+
+4. **Supports Additional Pages**: Allows configuration of additional pages to be displayed at the front of the breadcrumb trail via the `ADDITIONAL_PAGE` attribute (BreadcrumbsWidgetDefinition.java:79)
+
+## Visual Design
+
+The widget uses a distinctive arrow-style breadcrumb design with:
+- Alternating background colors for even/odd breadcrumb items
+- Arrow-shaped connectors between breadcrumb items (created with CSS borders)
+- Hover and active states for interactive feedback
+- Rounded corners on first and last items
+- 40px height with centered text (plugin.less:36-39)
+
+Visual example from screenshot (Breadcrumbs-001.png):
+```
+Sprint 4711/1 > Feature: Schedule Search in Schedule Selection Dialog > QA phase > Write test documents
+```
+
+## Use Cases
+
+### Primary Use Case: Page Hierarchy Navigation
+**When:** Users are viewing any page within a hierarchical workspace structure
+**Purpose:** Show the navigation path and enable quick navigation to parent pages
+**Example:** In a project management workspace, display the path from a task page through its parent sprint, feature, and project pages back to the workspace home
+
+### Use Case: Contextual Awareness
+**When:** Users need to understand where they are within a complex page hierarchy
+**Purpose:** Provide visual context about the current page's position in the structure
+**Example:** Help users understand that they are viewing a specific document that belongs to a QA phase, which is part of a larger feature, which belongs to a sprint
+
+### Use Case: Quick Navigation
+**When:** Users want to navigate to a parent or ancestor page
+**Purpose:** Enable one-click navigation to any page in the hierarchy without using back buttons
+**Example:** Quickly jump from a deep nested page directly to the workspace home or any intermediate level
+
+### Use Case: Custom Navigation Path
+**When:** Users want to add additional navigation links at the beginning of the breadcrumb trail
+**Purpose:** Include related pages or alternative entry points in the navigation path
+**Example:** Add a custom "Dashboard" or "Overview" page link at the start of the breadcrumb trail
+
+## Configuration Options
+
+### Main Configuration Attribute
+
+**Additional Pages** (`ADDITIONAL_PAGE`)
+- **Type:** Multi-Page Reference
+- **Multiplicity:** 0..* (any number)
+- **Description:** "Attach additional sides at the front" (messages_en.properties:5)
+- **Purpose:** Allows users to prepend additional page links to the beginning of the automatically generated breadcrumb path
+- **Use Case:** Add entry points or contextual pages that aren't part of the direct hierarchical path
+
+### Widget Display Settings
+
+The widget is configured with:
+- No frame/border around the widget content
+- No padding to allow seamless integration with page layouts
+- Icon: "cf-pase" (though this may be a typo in BreadcrumbsWidgetDefinition.java:49)
+
+## Technical Implementation Details
+
+### Java Implementation
+- **Definition Class:** `cf.cplace.breadcrumbs.script.BreadcrumbsWidgetDefinition`
+- **Configuration Type:** `BreadcrumbsWidgetTypes.BREADCRUMBS_WIDGET.TYPE`
+- **Key Method:** `getContentSubstitution()` creates template substitution with:
+  - `pathToRoot`: The list of pages from root to current page
+  - `additionalPages`: User-configured additional pages
+
+### Styling
+- **CSS Class:** `.cf-cplace-breadcrumbs-wrapper` containing `.cf-cplace-breadcrumbs`
+- **Customizable Variables:** Defined in `breadcrumbs-customizing-variables.less`
+  - Background colors (odd/even/hover/active)
+  - Font color
+  - Border color
+
+### Dependencies
+- Depends only on `cf.cplace.platform` (version 25.3.80)
+- No TypeScript or JavaScript assets (pure server-side rendering)
+
+## Relationship to Other Features
+
+### Core Platform Integration
+- **Pages:** Directly integrates with cplace's Page concept and hierarchy
+- **Workspaces:** Operates within the context of workspace home pages
+- **Layouts:** Typically added to page layouts to provide consistent navigation
+
+### Typical Placement
+Based on the screenshot and configuration (no frame, no padding), this widget is designed to be placed:
+- At the top of page layouts
+- Below the page title/header area
+- As a horizontal navigation bar spanning the page width
+
+## Notes
+
+- The widget only works with Page entities. When shown in a type definition layout where the entity is not a Page, `embeddingPage` will be null and an empty list is used (BreadcrumbsWidgetDefinition.java:70-72)
+- The breadcrumb path is automatically generated based on the page hierarchy, requiring no manual configuration for basic usage
+- The widget is purely presentational and uses server-side rendering (no client-side JavaScript)
+
+## Key Insights
+
+1. **Automatic Hierarchy**: The widget automatically derives the navigation path from the page structure, requiring minimal configuration
+2. **Flexible Extension**: The "additional pages" feature allows customization of the navigation path without breaking the automatic hierarchy
+3. **Consistent Navigation**: Provides a standard navigation pattern that can be applied across all pages in a workspace
+4. **Visual Design Focus**: The distinctive arrow-style design makes the navigation path immediately recognizable and visually distinct from other page content