## Overview

The Extended Tree Table Widget is a table with tree functionality that visualizes hierarchical relationships between pages in a table format with tree navigation. It excels at displaying complex hierarchies where different page types are organized in parent-child relationships, showing their attributes in configurable columns while handling cross-type scenarios gracefully.

Unlike simple hierarchical views, this widget supports dynamic hierarchy construction based on search criteria, configurable reference attributes that define parent-child relationships, and visual distinction for attributes that don't apply to certain types in the hierarchy.

## Use Cases

### Multi-Type Hierarchical Structures

The widget is ideal for displaying complex hierarchies where different page types are organized in parent-child relationships:

- **Project Management**: Program -> Project -> Task -> Subtask
- **Product Structures**: Product Line -> Product -> Component -> Part
- **Organizational Structures**: Division -> Department -> Team -> Individual
- **Document Hierarchies**: Category -> Document -> Section -> Paragraph

Each level in the hierarchy can be a different type, with different attributes, and the widget displays all relevant attributes across all types in a unified view.

### Cross-Type Relationship Visualization

When pages of different types form a hierarchy, attributes may not apply to all types. The widget handles this elegantly by:
- Displaying all attributes from all types in the hierarchy
- Using a configurable color (default gray) for cells where an attribute doesn't apply to a page's type
- Allowing users to see the complete picture across heterogeneous hierarchies without confusion

### Dynamic Hierarchy Construction

Unlike widgets with fixed hierarchies, this widget can:
- Use search filters to determine which pages participate in the hierarchy
- Select specific reference attributes that define parent-child relationships
- Support multiple incoming reference types (e.g., a child can have different parent types)
- Construct hierarchies on-the-fly based on user selection or search criteria

### Connected Widget Scenarios

The widget can interact with other widgets on the page for coordinated behavior:
- **Single Selection Widget Integration**: Display hierarchy starting from a selected page
- **Dynamic Root Node**: The hierarchy root can be determined by another widget's selection
- **Coordinated Filtering**: Multiple widgets can share context and filter data together

## Operating Modes

### Standalone Mode
The widget displays a hierarchy rooted at the embedding page or a configured root node. Users can explore the full tree structure with expand/collapse controls and filter by column values.

### Connected Mode
The widget's root node is determined by a selection in another widget (e.g., a single selection widget). As the user changes selection in the connected widget, the hierarchy updates dynamically.

The widget uses a clear priority order when determining the hierarchy root:
1. **Connected Table Selection** (highest priority) - Root from another widget's selection
2. **Configured Root Node** (medium priority) - Explicit page reference in widget configuration
3. **Embedding Page** (fallback) - The page where the widget is embedded

### Search-Based Mode
The widget uses search specifications to determine which pages participate in the hierarchy, allowing for dynamic filtering of the tree based on page properties beyond just the hierarchical relationships.

## Design Considerations

### When to Use This Pattern

Use the Extended Tree Table Widget when:
- You need to visualize hierarchical relationships with attribute details
- Your hierarchy spans multiple types with different attribute sets
- You want users to filter, sort, or search within the hierarchy
- You need dynamic hierarchy construction based on search criteria
- You want to integrate hierarchy visualization with other widgets

### When to Consider Alternatives

Consider other widgets when:
- Simple list or table view is sufficient (use Search as Table Widget)
- You don't need hierarchical navigation (use Table Widget)
- You only need to display a single type (simpler table widgets may suffice)
- You need specialized tree visualizations (consider custom tree widgets)

### Configuration Complexity

The widget requires careful configuration of:
- Reference attributes that define parent-child relationships (ATTRIBUTES configuration)
- Search specifications to filter participating pages
- Column configuration for attribute display
- Root node determination (embedded page, configured node, or connected widget)
- Default expansion depth based on hierarchy breadth and depth

Plan the hierarchy structure and reference attributes before configuring the widget.

### Default Expansion Depth Strategy

Consider the appropriate initial expansion depth based on your hierarchy characteristics:
- **Low depth (0-1)**: Best for broad hierarchies with many children per parent; users explore on demand
- **Medium depth (2-3)**: Balances immediate context with manageable visual complexity
- **High depth (4+)**: Suitable for narrow or shallow hierarchies where showing the full structure is valuable

## Common Pitfalls

- **Missing Reference Attribute Configuration**: The ATTRIBUTES configuration must define all parent-child relationship paths. Missing entries result in broken hierarchy paths.
- **Search Filter Too Restrictive**: If the search filter excludes pages that should be in the hierarchy, they won't appear even if correctly referenced.
- **Color Confusion**: In multi-type hierarchies, gray cells indicate non-applicable attributes. Users unfamiliar with this pattern may think data is missing.
- **Default Depth**: If not configured, only the first level expands by default. Consider setting DEFAULT_DEPTH based on typical hierarchy depth.
- **Root Node Ambiguity**: Without clear documentation, users may not understand whether the widget uses the embedding page, configured root, or connected selection as the starting point.

## Related Patterns

- **TreeTableWidget** (platform base widget): Abstract base class this widget extends
- **Search as Table Widget** (`cf.platform.embeddedSearchAsTable`): For non-hierarchical tabular data display
- **Single Selection Widget**: Often used to provide dynamic root selection for this widget
- **Table Widget** (platform): For simpler table displays without tree navigation

## Technical Notes

- Extends the platform's `TreeTableWidgetDefinition`
- Pure backend implementation (Java) with no frontend assets
- Hierarchy construction uses search-based child discovery
- Supports column-level filtering that persists in widget state
- Default non-relevant cell color: #BEBEBE (configurable)