@cplace/mcp-server 1.3.14

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

@@ -0,0 +1,150 @@
+# Template Placeholders Widget Research
+
+**Widget ID:** `cf.cplace.officeReports.templatePlaceholders`
+**Repository:** `cplace-office-reports`
+**Widget Name:** "Template" (English) / "Vorlage" (German)
+
+## Overview
+
+The Template Placeholders widget displays all placeholders that are detected in an Office report template file (PowerPoint, Word, or Excel). This widget parses the uploaded report template and shows users which placeholders are available for substitution during report generation.
+
+## Purpose
+
+This widget automatically extracts and displays placeholders from Office document templates (PPT, Word, Excel) to help users understand which placeholders exist in their template files and can be filled with data through scripts. It serves as a reference guide during report configuration.
+
+## Core Functionality
+
+### Placeholder Detection
+- **Automatic Parsing**: When a template file is uploaded to a Report Configuration page, the widget automatically parses the document to find all placeholders
+- **Pattern Recognition**: Placeholders are identified using the pattern `{.*?}` (text enclosed in curly braces)
+- **Format-Specific Parsing**: Uses different parsers based on report type:
+  - `PPTTemplatePlaceholderParser` for PowerPoint presentations
+  - `WordTemplatePlaceholderParser` for Word documents
+  - `ExcelTemplatePlaceholderParser` for Excel spreadsheets and Excel files with macros
+
+### Display Characteristics
+- **Format-Specific Tables**: Shows different table layouts depending on the document type:
+  - **PowerPoint**: Shows slide numbers, placeholder name, and type
+  - **Word**: Shows placeholder name and type
+  - **Excel**: Shows cell/table location, placeholder name, and type
+- **Status Indicators**: Displays validation messages:
+  - Success: Shows all detected placeholders
+  - Warning: Shows "Please select a template" if no template is uploaded
+  - Error: Displays error messages if parsing fails
+- **Sorting & Pagination**: Supports sortable columns and pagination for large numbers of placeholders
+
+## Use Cases
+
+### 1. Template Setup & Validation
+**When:** Setting up a new report configuration for the first time
+**User Action:** Upload an Office template file to the Report Configuration
+**Widget Benefit:** Immediately see which placeholders are available in the template, helping validate that the template was created correctly
+
+### 2. Script Development Reference
+**When:** Writing a cplace.js script to populate report data
+**User Action:** View the Template Placeholders widget while editing the script
+**Widget Benefit:** Know exactly which placeholder names to use in the `report.put(key, component)` calls without having to open and inspect the template file manually
+
+### 3. Template Maintenance
+**When:** Updating an existing report template with new placeholders
+**User Action:** Upload the updated template file
+**Widget Benefit:** See the updated list of placeholders, including any new ones added or removed ones missing
+
+### 4. Multi-Format Report Design
+**When:** Working with different Office formats (PPT vs Word vs Excel)
+**User Action:** Switch between different report types
+**Widget Benefit:** View format-specific information (e.g., slide numbers in PPT, cell locations in Excel) relevant to each document type
+
+### 5. Troubleshooting Report Generation
+**When:** A report is not generating correctly or placeholders are not being filled
+**User Action:** Check the Template Placeholders widget
+**Widget Benefit:** Verify that the placeholder names in the script match exactly what exists in the template (case-sensitive, exact spelling)
+
+## Configuration
+
+### Widget Configuration Options
+- **Height**: The widget supports a configurable height attribute (`TEMPLATE_PLACEHOLDERS_WIDGET.HEIGHT`)
+- **No Padding**: The widget renders without padding (`isNoPadding() = true`)
+- **Frame Display**: The widget displays with a frame (`showFrame() = true`)
+
+### Embedding Requirements
+This widget can ONLY be embedded in:
+- **Pages** of type `cf.cplace.officeReports.configuration` (Report Configuration)
+- **Type Definitions** of type `cf.cplace.officeReports.configuration`
+
+Attempting to embed this widget on any other page type will result in a `NotEmbeddableException`.
+
+## Technical Context
+
+### Data Source
+- **Template File**: The widget reads from the `cf.cplace.officeReports.reportTemplate` attribute on the Report Configuration page
+- **Report Type**: The widget adapts its display based on the `cf.cplace.officeReports.reportType` attribute (PPT, WORD, EXCEL, EXCEL_WITH_MACROS)
+- **Script**: The widget also has access to the report script configuration
+
+### Placeholder Model
+Each detected placeholder contains:
+- **placeholder**: The placeholder name/key (e.g., `{title}`, `{projectName}`)
+- **type**: The type of content the placeholder contains (e.g., "Text", "Cell", "Table")
+- **Additional metadata** depending on format:
+  - PowerPoint: slide numbers where the placeholder appears, optional table info
+  - Excel: cell location or table reference
+  - Word: type classification
+
+### REST API Integration
+- **Controller**: `TemplatePlaceholdersController`
+- **Endpoint**: `/cplace-fe/cf.cplace.officeReports/placeholders/template/load?config={reportConfigId}`
+- **Service**: `TemplatePlaceholdersService` handles the business logic
+- **Response**: Returns `LoadTemplatePlaceholderResponseDto` containing:
+  - Template placeholder data (set of `TemplatePlaceholder` objects)
+  - Report type
+  - Status (SUCCESS, WARNING, ERROR)
+  - Optional status message
+  - Associated script
+
+### Event Handling
+- **Refresh Event**: Listens to `EVENT_REFRESH_PLACEHOLDERS` to reload placeholders when the template changes
+- **Loading State**: Emits `EVENT_SET_LOADING` to show/hide loading indicators
+- **Data Loaded Event**: Emits `EVENT_TEMPLATE_PLACEHOLDERS_LOADED` when placeholders are successfully loaded
+
+## Relationship to Other Widgets
+
+### Related Office Reports Widgets
+
+1. **Script Placeholders Widget** (`cf.cplace.officeReports.scriptPlaceholders`)
+   - **Difference**: Shows placeholders that are dynamically defined in the script code, not in the template
+   - **Complementary**: Used together to show both template-based and script-based placeholders
+   - **Same Context**: Also only embeddable in Report Configuration pages
+
+2. **Generate Report Widget** (`cf.cplace.cplaceReportGeneration.generateReportWidget`)
+   - **Relationship**: The "Generate Report" widget uses the placeholders shown in this widget
+   - **Workflow**: Users configure templates and view placeholders, then generate reports using those placeholders
+
+3. **Headline for Reports Widget** (`cf.cplace.officeReports.headlineForReports`)
+   - **Relationship**: Another widget in the Office Reports suite for report configuration pages
+   - **Purpose**: Provides UI elements for report configuration, complementing the placeholder display
+
+### Integration with Report Configuration Type
+
+The widget is tightly integrated with the `cf.cplace.officeReports.configuration` type, which includes:
+- `reportTemplate`: Document reference attribute (the source for placeholder extraction)
+- `reportType`: Enum attribute (PPT, WORD, EXCEL, EXCEL_WITH_MACROS) determining parser behavior
+- `script`: Script attribute containing the cplace.js code that populates placeholders
+- `isConfigurationComplete`: Boolean indicating if the configuration is ready
+
+## Typical Page Layout
+
+A typical Report Configuration page includes:
+1. **Basic attributes** (Report Identifier, Report Type)
+2. **Template Upload** (Document attachment area for the template file)
+3. **Template Placeholders Widget** ← This widget (shows available placeholders from template)
+4. **Script Editor** (cplace.js script that uses the placeholders)
+5. **Script Placeholders Widget** (shows dynamically defined placeholders)
+6. **Generate Report Widget** (button to test report generation)
+
+## Key Insights
+
+1. **Read-Only Display**: This is a read-only widget that displays parsed information; users cannot edit placeholders directly
+2. **Automatic Updates**: The widget automatically refreshes when the template file changes
+3. **Validation Aid**: Helps prevent errors by showing exact placeholder names that must be used in scripts
+4. **Format-Aware**: Adapts its display and parsing logic based on the Office document format
+5. **Developer Tool**: Primarily used by report developers/administrators setting up report configurations, not by end users generating reports

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

@@ -0,0 +1,353 @@
+# Research: cf.cplace.orgaTree.edit Widget
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.orgaTree.edit`
+**Widget Name:** Edit Organizational Structure
+**Repository:** cplace-project-planning
+**Plugin:** cf.cplace.orgaTree
+**Definition Class:** `cf.cplace.orgaTree.script.EditOrgaTreeWidgetDefinition`
+
+## Short Description
+
+The Edit Organizational Structure widget provides an interactive tree view for managing organizational hierarchies, allowing users to create, edit, reorganize, and navigate departments, teams, members, and their associated schedules through drag-and-drop operations and context menus.
+
+## Purpose
+
+The `cf.cplace.orgaTree.edit` widget serves as the primary interface for managing organizational structures within cplace. It displays a hierarchical tree representation of an organization's structure, showing the relationships between departments, teams, users (persons), and their associated schedules.
+
+The widget enables users to:
+- Visualize the complete organizational hierarchy
+- Navigate through departments, subdepartments, teams, and team members
+- Reorganize the structure via drag-and-drop operations
+- Create new organizational entities (departments and teams) through context menus
+- Access and manage schedules associated with individual users
+- View access rights for organizational units
+
+## Use Cases
+
+### 1. Organizational Structure Management
+Users need to manage and maintain the organizational structure of their company or project.
+
+**Scenarios:**
+- Building an initial organizational structure for a new workspace
+- Updating the structure when teams are reorganized
+- Adding new departments when the organization grows
+- Restructuring departments by dragging and dropping them to new positions
+
+### 2. Team Management
+HR managers or department heads need to organize teams within departments.
+
+**Scenarios:**
+- Creating new teams within a department
+- Viewing all teams and their members at a glance
+- Reorganizing teams by moving them between departments
+- Managing team membership through the hierarchical view
+
+### 3. User Assignment and Overview
+Managers need to see which users belong to which departments and teams.
+
+**Scenarios:**
+- Getting an overview of all organizational members
+- Identifying which departments and teams a user belongs to (users can appear multiple times)
+- Accessing user profiles through the tree navigation
+- Managing user assignments to organizational units
+
+### 4. Schedule Management Access
+Users need to access schedules associated with organizational members.
+
+**Scenarios:**
+- Navigating to a user's own schedules through the organizational tree
+- Accessing substitute schedules where users are deputies
+- Managing project schedules in the context of organizational structure
+- Viewing and copying schedules directly from the organizational hierarchy
+
+### 5. Homepage and Navigation Hub
+The widget serves as the primary homepage for spaces with the Organizational Structure app.
+
+**Scenarios:**
+- Landing page when accessing an organizational structure workspace
+- Central navigation point for all organizational data
+- Quick access to create new organizational entities
+- Overview page for understanding organizational hierarchy
+
+## Core Functionality
+
+### Tree Structure Display
+
+The widget displays a hierarchical tree with the following node types:
+
+1. **Departments** (Root level and nested)
+   - Can have parent-child relationships (subdepartments)
+   - Contain users as direct members
+   - Contain teams as children
+   - Icon: `fa-users`
+
+2. **Teams**
+   - Must belong to a department
+   - Contain users as members
+   - Icon: `fa-user-plus`
+
+3. **Persons** (Users)
+   - Can belong to multiple departments and/or teams
+   - Expand to show associated schedules
+   - Display "Own schedules" and "Substitute schedules" as virtual nodes
+
+4. **Virtual Schedule Nodes**
+   - Own schedules: Schedules where the user is the owner
+   - Substitute schedules: Schedules where the user is a deputy
+   - These nodes expand to show actual schedule items
+
+5. **Schedules**
+   - Leaf nodes in the tree
+   - Can be copied through context menu
+   - Linked to project planning functionality
+
+### Interactive Features
+
+#### Drag-and-Drop Reorganization
+
+The widget supports drag-and-drop operations for reorganizing the hierarchy:
+
+- **Movable items:** Departments (can be moved to create subdepartments or change parent)
+- **Move validation:** Server-side validation via `CanMoveHandler` ensures only valid moves are allowed
+- **Caching:** Move validation results are cached on the target node to improve performance
+- **Permission check:** Users must have edit rights on the source node to move it
+
+**Implementation details:**
+- Position can be: "before", "after", or "inside" the target node
+- Only departments can currently be moved via drag-and-drop
+- The handler checks if the move is valid in the hierarchy (no circular references, valid parent-child relationships)
+
+#### Context Menu Actions
+
+The widget provides context-sensitive actions via right-click or dropdown menus:
+
+**For Departments:**
+- **New Department:** Create a new subdepartment
+- **New Team:** Create a new team within the department
+- **Open in new tab:** Navigate to the department page
+- **Edit access rights:** Open a user-rights matrix for all members in the department and its teams
+- **Delete:** Remove the department (if permissions allow)
+
+**For Teams:**
+- **New Team:** Create another team in the same department
+- **Open in new tab:** Navigate to the team page
+- **Edit access rights:** Open a user-rights matrix for all team members
+- **Delete:** Remove the team (if permissions allow)
+
+**For Schedules:**
+- **Copy:** Duplicate the schedule
+- **Open in new tab:** Navigate to the schedule page
+- **Delete:** Remove the schedule (if permissions allow)
+
+**For Persons and Virtual Nodes:**
+- **Open in new tab:** Navigate to the user profile or schedule
+
+### Data Loading
+
+The widget uses a lazy-loading approach:
+
+1. **Initial Load:** Root departments are loaded and displayed
+2. **Root nodes are auto-expanded:** Root elements have `load_on_demand: false` to show their immediate children
+3. **On-demand loading:** Child nodes are loaded when a parent node is expanded
+4. **Load URL:** The `LoadChildrenHandler` is called with the content provider ID to fetch child nodes
+5. **Content Provider:** `OrgaTreeContentProvider` handles all data retrieval and tree structure logic
+
+### Real-time Updates
+
+The widget listens to platform events:
+
+- **Page Creation:** When a new department or team is created, the parent node is reloaded and expanded
+- **Page Deletion:** When a department, team, or schedule is deleted, the node is removed from the tree
+- **Node Registration:** Nodes register themselves with the widget controller for event handling
+
+## Configuration
+
+The widget has minimal configuration requirements:
+
+### Widget Configuration
+
+- **Widget Kind:** `cf.cplace.orgaTree.edit`
+- **No custom parameters:** The widget automatically determines what to display based on the current workspace
+
+### Data Configuration
+
+The widget's behavior is configured through the `OrgaTreeContentProvider`:
+
+- **Root nodes:** All departments without a parent in spaces with the OrgaTree app
+- **Content Provider ID:** `orga_tree`
+- **Tab name:** "Organizational Structure"
+- **Order index:** 10 (determines position when multiple tree content providers exist)
+
+### Selection Mode
+
+The widget defines different selection modes for different node types:
+
+- **Departments:** `NONE` - Cannot be selected (navigation only)
+- **Teams:** `NONE` - Cannot be selected (navigation only)
+- **Persons:** `NONE` - Cannot be selected (navigation only)
+- **Groups:** `NONE` - Cannot be selected (navigation only)
+- **Virtual schedule nodes:** `CHILDREN` - Selecting the node selects all child schedules
+- **Schedules:** `SELF` - The schedule itself can be selected
+
+**Note:** In the current implementation, selection modes exist in the code but appear to be primarily for future functionality or integration with other widgets. The edit widget focuses on navigation and manipulation rather than selection.
+
+## Context and Relationships
+
+### Related Widgets
+
+1. **Project Tree Widget** (`cf.cplace.projectTree`)
+   - Similar hierarchical tree structure for project management
+   - Shares base classes and tree infrastructure (`TreeContentProvider`, `LoadChildrenHandler`)
+   - OrgaTree integrates with project tree through schedule management
+
+2. **Personal Tree Content Provider**
+   - Referenced from `ProjektplanungPlugin` for schedule management
+   - Provides "Own schedules" and "Substitute schedules" functionality
+   - Enables users to access their schedules through the organizational tree
+
+### App Integration
+
+The widget is part of the **Organizational Structure App** (`cf.cplace.orgaTree`):
+
+- **App display name:** "Organizational Structure"
+- **App description:** "The 'Organizational Structure' app lets you manage employees and teams in an organizational structure. This app offers you an organizational tree that helps you create, edit, and manage employees, teams, and sectors."
+- **Homepage widget:** This widget is automatically created as the homepage when the app is added to a workspace
+- **Type definitions:** The app defines DEPARTMENT and TEAM types
+
+### Dependencies
+
+**Backend dependencies:**
+- `cf.cplace.planauswahl` - Tree selection infrastructure (TreeContentProvider, TreeData, TreeItem)
+- `cf.cplace.projektplanung` - Schedule management and personal tree functionality
+- `cf.cplace.platform.frontend.handler.flexigrid.data` - Tree utilities and node interfaces
+
+**Frontend dependencies:**
+- AngularJS directive (`cfCplaceOrgaTreeEditWidget`)
+- jQuery tree widget (`cplace_jq_tree`)
+- Platform event system for real-time updates
+
+### Permission Model
+
+The widget respects cplace's permission system:
+
+- **Create:** Users need "create pages in same space" permission to add new departments/teams
+- **Edit/Move:** Users need edit rights on the source node to move it
+- **Delete:** Users need delete permissions on the entity
+- **Read:** The tree only shows entities the user has read access to
+
+## Technical Architecture
+
+### Backend Components
+
+**EditOrgaTreeWidgetDefinition.java:**
+- Widget registration and definition
+- Provides template substitution with tree data
+- Configures URLs for loading children and validating moves
+
+**OrgaTreeContentProvider.java:**
+- Implements `TreeContentProvider` interface
+- Handles data retrieval for all node types
+- Manages parent-child relationships
+- Provides bidirectional navigation (get children, get parents)
+- Handles both real nodes (pages, persons) and virtual nodes (schedule containers)
+
+**CanMoveHandler.java:**
+- Validates whether a department can be moved to a target position
+- Prevents invalid hierarchy structures
+- Uses `CanMoveMenuItemHandler.canMoveInHierarchy()` for validation
+
+**ContextMenuActionsProvider.java:**
+- Defines all available context menu actions
+- Implements permission checks for each action
+- Provides URLs for action execution
+
+### Frontend Components
+
+**cfCplaceOrgaTreeEditWidget.js:**
+- AngularJS directive that initializes the tree widget
+- Configures drag-and-drop behavior
+- Handles event listeners for page creation/deletion
+- Manages node registration for updates
+- Configures custom rendering templates
+
+**jQuery Tree Widget:**
+- Underlying tree rendering library
+- Handles tree state (expanded/collapsed)
+- Manages drag-and-drop interactions
+- Renders custom templates for different node types
+
+### Data Model
+
+**Type hierarchy:**
+```
+Department
+  - parent: Department (optional, creates hierarchy)
+  - users: Person[] (department members)
+  └─ subdepartments (incoming PARENT references)
+  └─ teams (incoming DEPARTMENT references)
+
+Team
+  - department: Department (required)
+  - users: Person[] (team members)
+
+Person (platform type)
+  └─ Virtual Node: Own Schedules
+      └─ Schedule[] (where person is owner)
+  └─ Virtual Node: Substitute Schedules
+      └─ Schedule[] (where person is deputy)
+```
+
+### Tree Node Types
+
+The implementation distinguishes between:
+
+1. **SimpleCustomEntityTreeNode:** Represents actual entities (departments, teams, persons, schedules)
+2. **VirtualSimpleTreeNode:** Represents virtual grouping nodes (schedule containers)
+3. **Node:** Legacy node interface for backward compatibility
+4. **ITreeNode:** Modern tree node interface
+
+## Key Implementation Details
+
+### Lazy Loading Mechanism
+
+1. Initial page load: Widget definition generates JSON with root departments
+2. Root nodes have `load_on_demand: false` - their children are included in initial data
+3. When user expands a node: Ajax call to `LoadChildrenHandler` with parent UID
+4. Handler delegates to `OrgaTreeContentProvider.getAllChildren()`
+5. Children are rendered and added to tree
+
+### Multi-parent Support
+
+Users can belong to multiple departments and/or teams:
+- Person nodes appear multiple times in the tree
+- Each appearance is a separate node with unique node ID
+- Node registration tracks which UIDs correspond to which node IDs
+- When a user is deleted, all instances are removed from the tree
+
+### Path Finding
+
+The widget supports finding paths from root to a specific node:
+- Used for highlighting and expanding to show a specific entity
+- Handles multiple possible paths (e.g., user belonging to multiple departments)
+- Can filter paths to only include specific required nodes
+
+### Caching Strategy
+
+The widget caches move validation results:
+- Each target node maintains a cache: `{sourceUid: {position: boolean}}`
+- Reduces server calls when dragging the same node over multiple positions
+- Cache is stored on the tree node object in the client
+
+## Limitations and Constraints
+
+1. **Move operations:** Only departments can be moved via drag-and-drop, not teams or users
+2. **Context menu:** Not all actions are available for all node types
+3. **Selection:** The edit widget is primarily for navigation and manipulation, not for selection
+4. **Permissions:** Actions are hidden if the user lacks permissions rather than being disabled
+5. **Real-time sync:** Updates are event-driven but only for create/delete, not for edit operations
+
+## Summary
+
+The `cf.cplace.orgaTree.edit` widget is a sophisticated hierarchical tree widget that serves as the central interface for managing organizational structures in cplace. It combines visualization, navigation, and manipulation capabilities in a single interactive component. The widget is designed for HR managers, department heads, and administrators who need to maintain organizational hierarchies, manage team structures, and access associated schedules. Its drag-and-drop functionality, context-sensitive actions, and integration with the broader cplace platform make it a powerful tool for organizational management.