## Overview

Lets you create and manage schedules and projects in the project structure tree.

The widget provides an interactive tree view for visualizing and managing the hierarchical structure of projects and schedules. It enables users to create, reorganize, and manage project hierarchies through drag-and-drop functionality, allowing restructuring of projects and schedules within the project tree.

The widget displays projects and their subprojects in an expandable/collapsible tree structure, shows schedules associated with each project, and supports both direct children and "additionally linked" projects/schedules (shown with a special icon to distinguish cross-references).

## Use Cases

### Portfolio Management Dashboard
PMO teams use this widget to get a visual overview of all projects, navigate the project hierarchy to find specific projects or schedules, and restructure projects as organizational needs change.

### Project Reorganization
Move projects to new parent projects when organizational structure changes, transfer schedules between projects when scope or responsibility shifts, and clean up project hierarchies by deleting unused projects.

### New Project/Schedule Creation
Create subprojects directly under a parent project, create schedules from templates within the project structure, and build out project hierarchies with nested subprojects through context menu actions.

### Cross-Project Relationships
View projects that appear in multiple locations via "Additional Project Links", and manage thematic relationships between projects without changing the primary hierarchy.

## Operating Modes

### Default Mode (All Root Projects)
When no configuration is set, the widget shows all root-level projects (projects without a parent) across all workspaces with the Project Structure app installed. This is useful for organization-wide portfolio views.

### Filtered by Selection Mode
Explicitly select specific projects as roots via the `rootProjects` attribute. Only those projects and their children appear in the tree. Useful for focused views on specific project groups.

### Filtered by Search Mode
Define a search query via the `rootProjectsSearch` attribute to dynamically find root projects. Can be combined with explicit selections (explicit + search results). Useful for dynamic views based on project attributes.

## Design Considerations

### When to Use This Widget
Use this widget when users need to manage the overall project structure, create new projects/schedules, or reorganize existing hierarchies. Typical placement is on a dedicated "Project Structure" or "Portfolio" page, or on a project's dashboard to show its subprojects.

### Problems It Solves
- Provides a visual representation of complex project hierarchies that would be hard to understand in a flat list
- Enables restructuring without navigating to individual project pages
- Centralizes project/schedule creation actions in one interface
- Shows cross-linked projects without duplicating the actual project data

### Permission and Access Handling
The widget respects access permissions and only shows items the user can read. If configured root projects exist but the user cannot see them (permissions), it displays an info message about invisible projects. The widget validates permissions before allowing moves, prevents moving a project into its own subtree (circular reference), and respects the "Project Structure Editor" role for restructuring permissions.

## Key Interactions

### Drag-and-Drop Reorganization
Users can move projects to different parent projects, move schedules to different parent projects, reorder projects within the same parent (projects maintain an order index), and move additionally linked items between parents.

### Context Menu Actions
Right-clicking on items in the tree provides actions for:
- Create Subproject (direct creation)
- Create Subproject from Template
- Create Schedule (new or from template)
- Delete project/schedule
- Open in new tab
- Unlink project (for additionally linked items)

## Related Patterns

### Part of Project Structure App
This widget is part of the Project Structure (`cf.cplace.projectTree`) app, which includes the Project type with parent/child relationships and "Additional Project Links", Schedule parent-project reference for organizing schedules under projects, Project Structure Editor role for users who can restructure projects but not edit their content, and template-based creation for projects and schedules.

### Dependencies
- **cf.cplace.planauswahl** - Provides the tree view infrastructure and base classes
- **cf.cplace.projektplanung** - Provides Schedule type definitions

The Project Structure app must be installed in the workspace, and Projects and Schedules must have the standard type definitions from the Project Planning solution.

## Display Considerations

- "Linked" items (via Additional Project Links) display with a different icon to distinguish them from direct children
- Schedules appear before subprojects within each project node
- The tree uses lazy loading for children to maintain performance with large hierarchies
- Tree roots are initially expanded; child nodes load on demand
- Root projects from search are sorted alphabetically
- Direct children projects are sorted by order index (manually orderable)
- Schedules are sorted by name