## Overview

> **Do not use this widget unless explicitly requested.** Consider bar charts, tables with grouping, or other visualization approaches for two-dimensional data analysis.

Visualizes the content of a table broken down according to two search criteria.

The Connected Matrix Widget organizes pages from a search result into a two-dimensional grid structure based on two configurable attributes. Each axis represents a categorical dimension (such as team members, time periods, risk levels, or features), and the intersection cells contain the pages matching those coordinate combinations.

As part of the "connected widget" family, this widget integrates with a table widget to share search queries, filters, and permissions. This makes it particularly valuable for visualizing relationships and distribution patterns that would be difficult to spot in traditional list or table formats.

## Primary Use Cases

### Responsibility Assignment (RACI Matrix)
- **X-axis**: Team members or organizational roles
- **Y-axis**: Tasks, deliverables, or activities
- **Purpose**: Show who is responsible, accountable, consulted, or informed for each task
- **Value**: Quickly identify gaps in responsibility coverage or overallocation

### Risk Assessment Matrix
- **X-axis**: Risk likelihood (Low, Medium, High)
- **Y-axis**: Risk impact (Low, Medium, High)
- **Purpose**: Position risks by probability and severity
- **Value**: Visual prioritization based on standard risk management framework

### Resource Allocation Over Time
- **X-axis**: Time periods (weeks, months, quarters)
- **Y-axis**: Projects, teams, or resources
- **Purpose**: Show which resources are allocated where and when
- **Value**: Identify scheduling conflicts and resource constraints

### Product Feature Comparison
- **X-axis**: Products or product versions
- **Y-axis**: Features or requirements
- **Purpose**: Show feature availability across product lines
- **Value**: Gap analysis and feature parity visualization

### Stakeholder Mapping
- **X-axis**: Interest level in the project
- **Y-axis**: Influence or power level
- **Purpose**: Map stakeholders by engagement characteristics
- **Value**: Guide communication and engagement strategies

### Cross-Functional Dependencies
- **X-axis**: Departments or organizational units
- **Y-axis**: Projects or initiatives
- **Purpose**: Visualize organizational dependencies
- **Value**: Identify collaboration needs and organizational silos

## Design Considerations

### When to Use This Widget

Choose the Connected Matrix Widget when:
- You need to visualize relationships between **two categorical dimensions** (not continuous data)
- Distribution patterns or concentrations matter more than individual details
- Users need to quickly identify gaps, conflicts, or categorization at a glance
- The data naturally maps to a grid structure (like assignments, allocations, or assessments)
- Both dimensions have a manageable number of distinct values (typically 3-20 per axis)

### When to Consider Alternatives

**Use a Table Widget instead** when:
- You need detailed data with multiple columns
- Sorting and filtering by many attributes is important
- Users need to see all attribute values, not just two dimensions
- The focus is on individual records rather than distribution patterns

**Use a Chart Widget (Bar/Pie) instead** when:
- You only have one dimension to visualize
- You need to show proportional distribution rather than absolute positioning
- Aggregate counts or percentages are more important than individual items

**Use a Timeline/Gantt Widget instead** when:
- Time is a continuous axis (not discrete periods)
- Duration and scheduling are the primary concerns
- Dependencies between tasks need to be visualized

**Use a Tree Table Widget instead** when:
- Hierarchical relationships are more important than dimensional categorization
- Parent-child structures define the organization
- Drill-down through levels is the primary navigation pattern

### Attribute Selection Guidelines

**Good candidates for axes**:
- Enumeration attributes with 3-20 values (ideal range)
- Reference attributes to organizational entities (people, teams, departments)
- Date attributes that naturally group (quarters, months)
- Categorical attributes that represent discrete states or categories

**Poor candidates for axes**:
- Free-text strings with many unique values
- Continuous numeric ranges (use charts instead)
- Attributes with too many values (matrix becomes unwieldy)
- Optional attributes where most pages lack values

### Visual Styles

The widget supports different visual styles for axis headers:
- **Plain**: Simple text labels (default, works for all attribute types)
- **Label**: Styled label boxes (good for enumeration values)
- **Arrow**: Labels with arrow indicators (useful for directional progression)
- **Profile-line/Profile-column**: User profile images (for Person references)

Choose the style that best matches your data type and visual design needs.

### Performance Considerations

- **Default limit**: 500 pages (configurable via `MAX_RESULTS`)
- Matrices work best with **focused searches** that return relevant subsets
- Very large matrices (many values on both axes) can impact browser performance
- Consider using connected table filters to let users narrow down results dynamically

### Cell Population Patterns

**Enumeration attributes**:
- All enumeration values appear as lanes (rows/columns)
- Empty cells are visible but contain no links
- Helps identify gaps (e.g., "no one is responsible for this task")

**Other attribute types**:
- Only values present in search results create lanes
- Empty lanes are omitted entirely
- Matrix size adapts to actual data

## Connection Patterns

### Required Connected Widget
The matrix widget **requires** a table widget connection:
- Shares the table's search query and filters
- Inherits permission settings from the table
- Updates when table filters change

**Setup**: Configure `TABLE_WIDGET_ID` to point to the source table widget

### Optional Connected Widgets
Works well with:
- **Connected Table Filter** widgets: Provide interactive filtering controls
- **Connected Bar/Pie Chart** widgets: Offer alternative visualizations of the same data
- **Connected Single Attribute** widgets: Show aggregate metrics alongside the matrix

All connected widgets sharing the same table stay synchronized.

## Common Pitfalls

### Matrix Size Management
**Problem**: Too many unique values create an unwieldy matrix
**Solution**:
- Refine the search query to focus on relevant subsets
- Use enumeration attributes with controlled value sets
- Add connected filter widgets to let users narrow results
- Consider grouping continuous attributes (e.g., date ranges instead of individual dates)

### Attribute Coverage
**Problem**: Pages without X or Y attribute values are excluded from display
**Solution**:
- Ensure the search query targets types with both attributes defined
- Make attributes required if all pages should appear
- Use validation rules to ensure data quality

### Multiple Pages Per Cell
**Problem**: Cells with many pages become crowded and hard to read
**Solution**:
- Use icon attributes to provide visual differentiation
- Refine search to reduce result count
- Consider whether the axes are granular enough
- Accept that this is a high-level overview (users click through for details)

### Profile Image Display
**Problem**: Profile images don't appear even with profile-line/profile-column style
**Solution**:
- Ensure the axis uses a Person reference attribute
- Verify that Person pages have profile images uploaded
- Check that thumbnail generation is configured correctly in cplace

## Related Patterns

### Connected Widget Family
All widgets sharing the `cf.platform.connected*` naming pattern integrate with table widgets:
- `cf.platform.connectedBarChart` - Bar chart visualization
- `cf.platform.connectedPieChart` - Proportional distribution
- `cf.platform.connectedTableFilter` - Interactive filtering controls
- `cf.platform.connectedSingleAttribute` - Single value display
- `cf.platform.connectedAttributesGroup` - Multi-attribute grouping

### Alternative Visualizations
Depending on your data and goals, consider:
- `cf.cplace.platform.tableWidget` - Detailed tabular view
- `cf.cplace.extendedTreeTableWidget` - Hierarchical data
- Timeline widgets - Time-phased planning
- Chart widgets - Aggregated metrics