@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-projektplanung-singleGantt/research.md

@@ -0,0 +1,184 @@
+# Single Gantt Widget Research
+
+**Widget ID:** `cf.projektplanung.singleGantt`
+**Widget Name:** Gantt chart (EN) / Gantt-Diagramm (DE)
+**Repository:** `cplace-project-planning`
+**Definition Class:** `cf.cplace.projektplanung/src/main/java/cf/cplace/projektplanung/script/SingleGanttWidgetDefinition.java`
+
+## Purpose
+
+The Single Gantt widget displays a Gantt chart visualization of all tasks and milestones belonging to a single schedule. It automatically identifies and displays the schedule context by traversing the page hierarchy upward to find the parent schedule.
+
+**1-2 Sentence Description:**
+The Single Gantt widget renders an interactive Gantt chart showing all tasks and milestones of a schedule, automatically detecting the schedule context from the page hierarchy. It provides visual project planning capabilities with timeline visualization, task dependencies, and milestone tracking for a single schedule.
+
+## Core Functionality
+
+### Automatic Schedule Detection
+- The widget uses `SingleGanttSubstitution` to automatically find the parent schedule
+- When embedded on a page, it recursively traverses up the page hierarchy (`findSchedule()` method) until it finds a page of type `SCHEDULE`
+- This allows the widget to be embedded on any page within a schedule's hierarchy without manual configuration
+- The search includes cycle detection to prevent infinite loops
+
+### Schedule Context
+A **Schedule** (`cf.schedule`) is a fundamental entity type in the project planning domain that:
+- Represents a project plan or schedule
+- Contains tasks, milestones, and their relationships
+- Serves as the root container for project planning data
+- Uses the icon "cf-gantt-square-o"
+
+### Key Characteristics
+- **Single schedule focus**: Unlike the Multi Gantt widget, this displays only one schedule at a time
+- **No manual schedule selection**: The schedule is determined automatically based on page context
+- **Full Gantt functionality**: Provides complete Gantt chart features including task visualization, dependencies, and timeline management
+- **Embeddable anywhere**: Can be embedded on the schedule page itself or any child page within the schedule hierarchy
+
+## Use Cases
+
+### Primary Use Case
+Display a comprehensive Gantt chart view of a single schedule when viewing:
+- A schedule page directly
+- Any page that belongs to a schedule (task pages, milestone pages, etc.)
+- Custom pages embedded within a schedule context
+
+### When to Use Single Gantt vs Multi Gantt
+
+**Use Single Gantt when:**
+- You want to display the schedule that is contextually relevant to the current page
+- The widget is embedded on a schedule page or one of its child pages
+- You need automatic schedule detection without configuration
+- Users are working within the context of a single project/schedule
+
+**Use Multi Gantt when:**
+- You need to display multiple schedules simultaneously
+- You want to compare multiple projects side by side
+- Schedules need to be explicitly selected via configuration
+- The widget is on a dashboard or overview page without schedule context
+
+### Common Scenarios
+1. **Schedule Overview Page**: Embedded directly on a schedule page to show all tasks and milestones
+2. **Task Detail Pages**: Embedded on individual task pages to show the parent schedule's full Gantt view
+3. **Custom Schedule Views**: On custom pages within a schedule hierarchy where context-aware Gantt visualization is needed
+
+## Configuration Options
+
+The Single Gantt widget inherits configuration from `ABSTRACT_GANTT` and `BASIS_GANTT`:
+
+### Time Range Configuration
+- **Start Date** (`startDate`): Absolute start date for the Gantt view
+- **Relative Start Date** (`relativeStartDate`): Dynamic start date relative to today (in days)
+- **End Date** (`endDate`): Absolute end date for the Gantt view
+- **Relative End Date** (`relativeEndDate`): Dynamic end date relative to today (in days)
+
+### Display Options
+- **Initial Expansion State** (`initialExpansionState`): Controls the tree expansion level when loading
+  - All Expanded: Shows all tasks and subtasks expanded
+  - Schedules Expanded: Shows only the schedule level expanded
+  - All Collapsed: Shows everything collapsed initially
+  - Default: Uses application-level default if not set
+
+- **Read Protection** (`readProtection`): Controls edit permissions
+  - Writeable (default): Tasks can be edited in the Gantt view
+  - Read-only: Gantt is displayed but no editing allowed
+
+- **Number of Rows** (`numberOfRows`): Sets the height of the diagram in number of rows
+
+- **Without Cross-Links** (`withoutCrossLinks`):
+  - When enabled (default: true), does not load tasks linked from outside the selected schedule
+  - Prevents loading of external dependencies and cross-linked tasks
+  - Note: Cross-links cannot be modified until they are loaded in the widget
+
+## Technical Details
+
+### Class Hierarchy
+```
+WidgetDefinition (platform)
+  └─ SingleGanttWidgetDefinition
+       └─ Uses: SingleGanttSubstitution
+            └─ Extends: GanttSubstitution
+                 └─ Extends: BaseGanttSubstitution
+```
+
+### Embedding Rules
+- Can be embedded on any page or type (checked at runtime via `checkEmbeddableIn`)
+- Looks up parent schedule dynamically rather than requiring specific entity types
+- **Cannot coexist** with another Single Gantt or Multi Gantt widget on the same page (enforced via `checkShowInSelection`)
+
+### Configuration Limitations
+- **Not configurable in view**: The widget cannot be configured inline and requires a full page reload when configuration changes (noted in `isConfigurableInView()`)
+- This is a known limitation related to the Gantt diagram's rendering mechanism
+
+### Configuration Storage
+- Uses TypeDef: `de.infoasset.projektplanung.SingleGantt` (legacy name maintained for compatibility)
+- Configuration is stored using the attribute definitions from `WidgetTypes.SINGLE_GANTT`
+
+### Migration Support
+- Includes migration logic for unlocalized enum texts (changed in version 4.39)
+- Old German values ("Alle aufgeklappt", "Pläne aufgeklappt", "Alle eingeklappt") are migrated to internal enum values
+- Migration happens on-the-fly and must be kept indefinitely or require an actual data migration
+
+## Relationships to Other Widgets
+
+### Related Widgets
+1. **Multi Gantt Widget** (`cf.projektplanung.multiGantt`):
+   - Displays multiple schedules simultaneously
+   - Requires explicit schedule selection
+   - Cannot be on the same page as Single Gantt
+
+2. **Gantt Link Widget** (`cf.projektplanung.singleGanttLink`):
+   - Related widget with similar structure
+   - Likely provides linking functionality between Gantt charts
+
+3. **Schedule Tree Widget** (`cf.cplace.projektplanung.scheduleTree`):
+   - Alternative view for schedules in tree/table format
+   - Provides hierarchical view without timeline visualization
+
+### Part of Project Planning Feature Set
+The widget is part of the comprehensive project planning plugin (`cf.cplace.projektplanung`) which includes:
+- Task and milestone management
+- Dependency handling (create, update, delete)
+- Schedule calculations and locking
+- Import/Export capabilities (MPX format)
+- Baseline and timebox support
+- Activity classes and custom layouts
+- Personal column views and favorites
+- Subscription management
+
+### Prerequisites
+- Requires the `cf.cplace.projektplanung` plugin (ProjektplanungPlugin)
+- Depends on base Gantt functionality from `cf.cplace.gantt` plugin
+- Uses shared types from `cf.cplace.projectPlanningBase`
+
+## Configuration Data Model
+
+The widget uses `GanttConfig` class which extends `BaseGanttConfig`:
+
+**Base Configuration:**
+- `anfangsDatum`: Start date
+- `endDatum`: End date
+- `readOnly`: Read-only flag
+- `diagramRows`: Number of diagram rows
+
+**Extended Configuration:**
+- `ignoreCustomAttributes`: Whether to ignore custom attributes
+- `rootIds`: List of schedule IDs to display (populated automatically via `extractRootIds`)
+- `alreadyLoadedRootIds`: Tracks loaded schedules for incremental loading
+- `schedulesFavoriteId`: ID of saved favorite configuration
+- `ganttTabMode`: Whether in tab mode
+- `addExternalDependencyTasks`: Whether to include external dependencies
+- `initialExpansionState`: Tree expansion state on load
+- `filteredRows`: Set of filtered row IDs
+- `loadMode`: Controls what data to load (ALL, ADDITIONAL_TASKS, ADDITIONAL_SCHEDULES)
+- `allExternalTaskIds`: All cross-linked external task IDs
+- `additionalExternalTaskIds`: Additional external tasks to load
+
+## Key Differentiators
+
+**Automatic Context Detection:**
+The main differentiator of Single Gantt is its automatic schedule detection through page hierarchy traversal, making it ideal for embedding in schedule-related pages without manual configuration.
+
+**Simplicity vs Flexibility:**
+Single Gantt trades configuration flexibility (no manual schedule selection) for simplicity and automatic context awareness, making it the preferred choice for schedule-centric views.
+
+**Single Responsibility:**
+Focuses solely on displaying one schedule's tasks and milestones, providing a focused view without the complexity of multi-schedule management.

package/dist/widget-specifications/_research_from_ga_products/cf-projektplanung-singleGanttLink/research.md

@@ -0,0 +1,188 @@
+# Widget Research: cf.projektplanung.singleGanttLink
+
+## Widget Description
+
+The `cf.projektplanung.singleGanttLink` widget is **a button that opens a Gantt chart in a new browser tab for one or more schedules**. It provides flexible schedule selection options and can be embedded on any page to give users quick access to Gantt visualizations.
+
+## Core Purpose
+
+This widget serves as a navigation bridge between pages and Gantt chart visualizations. Instead of embedding a full Gantt chart directly on a page (which can be resource-intensive), this widget provides a lightweight button that opens the Gantt view in a separate tab when clicked. This approach is useful when you want to provide access to Gantt visualizations without the overhead of rendering them inline.
+
+## Use Cases
+
+### 1. Schedule Overview Pages
+Embed the widget on dashboard or overview pages where users need quick access to view schedules in Gantt format without cluttering the page with a full Gantt visualization.
+
+**Example**: A project portfolio page that lists multiple projects, each with a button to open its schedule in Gantt view.
+
+### 2. Cross-Reference Navigation
+Place the widget on pages that reference schedules to provide direct navigation to the Gantt visualization of related schedules.
+
+**Example**: A milestone page that has a button to open the parent schedule's Gantt chart.
+
+### 3. Dynamic Schedule Access
+Use search-based or attribute-based selection to dynamically determine which schedule(s) to open based on the current page context.
+
+**Example**: A task page that automatically opens the Gantt view for its associated schedule based on a reference attribute.
+
+### 4. Multi-Schedule Gantt Access
+Configure the widget to open multiple schedules simultaneously in a combined Gantt view (up to 100 schedules).
+
+**Example**: A program management page with a button to open Gantt views for all schedules within a specific program or portfolio.
+
+### 5. Filtered Gantt Views
+Combine with the "without crosslinks" option to open Gantt charts that focus only on tasks within the selected schedules, excluding external dependencies.
+
+**Example**: A standalone project view where you only want to see internal project tasks without cross-project dependencies.
+
+## Key Concepts and Features
+
+### Schedule Selection Modes
+
+The widget supports **four different modes** for selecting which schedule(s) to open:
+
+#### 1. Embedding-Based Selection (Default)
+- Uses the page where the widget is embedded as the schedule to open
+- Best for: Schedule pages where the widget opens the current schedule's Gantt view
+- Configuration: Selected as "Data source" → embedding-based option
+
+#### 2. Absolute/Explicit Selection
+- Explicitly select specific schedule page(s) in the widget configuration
+- Supports multiple schedules (multi-page reference)
+- Best for: Fixed navigation to specific known schedules
+- Configuration: "Data source" → explicit selection, then choose schedules via "Schedules" attribute
+
+#### 3. Relative/Attribute-Based Selection
+- Dynamically selects schedules based on a reference attribute of the embedding page
+- Follows relationships from the current page to referenced schedule(s)
+- Best for: Context-aware navigation where schedule relationship is defined by page attributes
+- Configuration: "Data source" → attribute-based selection, then choose the attribute via "Reference to the schedule to be opened"
+
+#### 4. Search-Based Selection
+- Uses a search query to find schedules dynamically at runtime
+- Supports sorting by attribute and sort order (ascending/descending)
+- Automatically filters to only return Schedule type pages
+- Limited to maximum 100 schedules
+- Best for: Opening multiple schedules based on complex criteria
+- Configuration: "Data source" → search-based, then define search criteria, sort column, and sort order
+
+### Configuration Options
+
+#### Button Text (`BUTTON_TEXT`)
+- **Type**: Localized string (optional)
+- **Purpose**: Customize the text displayed on the button
+- **Default**: "Open Gantt chart" (localized)
+- **Use**: Provide context-specific button labels like "View Project Timeline" or "Open Master Schedule"
+
+#### Without Crosslinks (`WITHOUT_CROSSLINKS`)
+- **Type**: Boolean
+- **Purpose**: Controls whether cross-linked tasks from external schedules are shown in the Gantt view
+- **Default**: `true` (crosslinks excluded)
+- **Use**:
+  - `true` - Show only tasks belonging to the selected schedule(s), providing a focused view
+  - `false` - Include tasks from other schedules that have dependencies to tasks in the selected schedule(s)
+
+### UI Behavior
+
+The widget renders as either:
+
+1. **Icon-only button** (when `hideLabel` is true)
+   - Shows a folder-open icon
+   - Tooltip displays the button text on hover
+   - Compact display suitable for tables or tight spaces
+
+2. **Button with text** (default)
+   - Shows button text alongside icon
+   - More prominent and self-explanatory
+
+3. **Disabled state**
+   - Shown when no valid schedule is found based on the selection criteria
+   - Displays "Open Gantt chart (Schedule not found)" message
+   - Prevents navigation to an invalid view
+
+The button always opens in a new browser tab by default (`target="_blank"`), keeping the original page context intact.
+
+## Relationship to Other Widgets
+
+### Single Gantt Widget (`cf.projektplanung.singleGantt`)
+- **Difference**: The Single Gantt widget embeds the full Gantt visualization directly on the page
+- **Relationship**: Both visualize schedule data, but singleGanttLink provides a navigation button instead of inline rendering
+- **Trade-off**: singleGanttLink is lighter weight but requires navigation; singleGantt provides immediate visualization but is more resource-intensive
+
+### Multi Gantt Widget (`cf.projektplanung.multiGantt`)
+- **Difference**: Multi Gantt embeds multiple schedules' Gantt charts on the same page
+- **Relationship**: singleGanttLink can open multiple schedules in a combined Gantt view in a new tab
+- **Trade-off**: Similar to Single Gantt comparison - link vs. embedded approach
+
+### Widget Selection Logic
+The widget definition includes logic to prevent embedding both Single Gantt and Multi Gantt widgets on the same page (`checkIsNotAlreadyEmbedded`), indicating they serve mutually exclusive purposes. The singleGanttLink widget has no such restriction and can coexist with embedded Gantt widgets.
+
+## Technical Implementation Notes
+
+### Widget Type
+- **ID**: `cf.projektplanung.singleGanttLink`
+- **Definition Class**: `GanttLinkWidgetDefinition` (cf.cplace.projektplanung/script/GanttLinkWidgetDefinition.java:55)
+- **Helper Class**: `ViewGanttLinkButton` (handles button rendering)
+- **Handler**: Uses `ViewGanttHandler` for opening the Gantt view
+
+### Embedding Restrictions
+- Can be embedded in widget containers or rich text
+- Can be placed on any Page type
+- Validates that it's used within the appropriate app space
+- Looks up parent schedule at runtime rather than at configuration time
+
+### Schedule Selection Architecture
+The widget uses a sophisticated attribute grouping system (`ScheduleSelectionGrouping`) that provides:
+- Pluggable selection strategies via `ScheduleSelectionGroup` implementations:
+  - `EmbeddingScheduleSelectionGroup` - uses embedding page
+  - `AbsoluteScheduleSelectionGroup` - uses explicit selection
+  - `RelativeScheduleSelectionGroup` - uses attribute reference
+  - `SearchScheduleSelectionGroup` - uses search query
+  - `ConnectedTableScheduleSelectionGroup` - uses connected table data (additional option)
+
+### URL Generation
+The widget generates a URL to `ViewGanttHandler` with parameters:
+- `SELECTED_PLAN_IDS_PARAMETER`: Comma-separated list of schedule IDs to open
+- `WITHOUT_EXTERNAL_DEPENDENCY_TASKS_PARAMETER`: Boolean controlling crosslink visibility
+
+### Attribute Migration Support
+The widget includes logic to handle attribute name migrations (cf.cplace.projektplanung/script/GanttLinkWidgetDefinition.java:238-289):
+- Migrates custom attribute names in relative selection
+- Updates search queries during migration
+- Handles sort attribute migration for search-based selection
+
+## Configuration Best Practices
+
+1. **Choose the right selection mode**:
+   - Use embedding-based when the widget is on Schedule pages
+   - Use absolute selection for fixed navigation links
+   - Use relative selection when page relationships define the schedule
+   - Use search when you need dynamic multi-schedule access
+
+2. **Button text customization**:
+   - Keep it concise (2-4 words)
+   - Make it action-oriented: "View Timeline", "Open Schedule", etc.
+   - Leave empty to use the default localized text
+
+3. **Crosslinks setting**:
+   - Enable crosslinks (`false`) when dependencies between schedules are important
+   - Disable crosslinks (`true`) for focused, single-schedule views
+   - Default is disabled for better performance
+
+4. **Search-based selection**:
+   - Always define meaningful sort criteria for predictable results
+   - Be aware of the 100-schedule limit
+   - The widget automatically adds a filter for Schedule type, so no need to specify it in search
+
+## Internationalization
+
+The widget is fully internationalized with support for at least English and German:
+- Widget name: "Open Gantt Chart"
+- Widget description: "A button that opens a Gantt chart in a new browser tab."
+- Default button text: "Open Gantt chart"
+- Error message: "Open Gantt chart (Schedule not found)"
+- All configuration attribute labels and help texts are localized
+
+## Summary
+
+The `cf.projektplanung.singleGanttLink` widget is a flexible, lightweight navigation component that provides users with quick access to Gantt chart visualizations. Its strength lies in its multiple selection modes, which allow it to adapt to different page contexts and use cases - from simple navigation buttons on schedule pages to sophisticated search-based multi-schedule access. By opening Gantt views in a new tab rather than embedding them inline, it offers a good balance between functionality and performance.