## Overview

Generates a table of search results.

The Embedded Search Table displays a filtered list of pages in a tabular format. It is the most versatile and commonly used widget for presenting collections of data in cplace.

**Use when you need to:**
- Show a list of pages matching certain criteria
- Enable users to browse, sort, and select from a collection
- Create master-detail interactions between widgets
- Display related entities on a page detail view

**Alternatives:**
- **New Table Widget** (`cf.cplace.platform.tableWidget`) - **Preferred alternative for new implementations.** Modern web component architecture with multi-column sorting, advanced filtering, and multi-producer support.
- **Embedded Search as List** - Simpler card-based display without columns

## Operating Modes

### Standalone Mode

The table operates independently, showing results based on its own search criteria. This is the simplest mode—define what pages to show, and the table displays them.

**Typical scenarios:**
- A list of all active projects in a workspace
- Showing open tasks assigned to the current user
- Displaying recent documents matching a category

### Master Mode

The table serves as a selection source for other widgets. When a user selects a row, connected widgets update to show related information.

**Typical scenarios:**
- Project list where selecting a project updates charts and detail panels
- Resource list driving a capacity timeline view
- Category browser controlling what appears in detail tables

### Detail Mode

The table reacts to selections made in another widget. Its contents filter dynamically based on what the user selected elsewhere.

**Typical scenarios:**
- Showing tasks belonging to a selected project
- Displaying team members assigned to a selected department
- Listing documents related to a selected category

### Embedding Context Mode

When placed on a page detail layout, the table can automatically filter to show entities related to that specific page. The table "knows" which page it's embedded on and uses that context.

**Typical scenarios:**
- On a Project page: showing all tasks belonging to this project
- On a Person page: showing all assignments for this person
- On a Category page: showing all items in this category

## Design Considerations

### When to Use Master-Detail

Master-detail patterns work well when:
- Users need to explore relationships between entities
- The detail view would be too cluttered without context
- There's a clear parent-child or one-to-many relationship

Avoid master-detail when:
- Each table serves an independent purpose
- Users need to see all information simultaneously
- The relationship between data sets isn't intuitive

### Scoping to Workspace

Tables should almost always be scoped to the current workspace. This prevents data leakage across workspaces and ensures users only see relevant content. Cross-workspace tables are rare and require explicit justification.

### Showing Multiple Types

A single table can display pages of different types. This is useful for unified views (e.g., "all requests and responses") but requires careful column selection since different types have different attributes. Include a type indicator column so users can distinguish between row types.

### Negation Filters

Sometimes it's easier to define what you *don't* want rather than what you do. Negation filters exclude matching items, which is useful for:
- Showing "everything except active items" (catches future status values automatically)
- Excluding specific categories without listing all included ones
- Creating complementary table pairs (active vs. inactive)

## Connection Patterns

### Driving Charts and Visualizations

Tables can drive chart widgets. When users select rows in the table, charts update to reflect that selection. This creates interactive dashboards where the table serves as a data navigator.

### Cascading Detail Tables

Multiple tables can form a hierarchy: Table A drives Table B, which drives Table C. This enables drill-down exploration through data relationships (e.g., Portfolio → Projects → Tasks).

### Coordinated Height

When tables appear side-by-side in master-detail layouts, matching their heights creates visual harmony and makes the relationship between them clearer.

## Common Pitfalls

- **Missing connection setup** - Detail tables need both the connection reference and the appropriate search filter; one without the other won't work
- **Overly broad searches** - Forgetting to scope to workspace can surface unexpected data from other contexts
- **Column mismatch** - Specifying columns that don't exist on the searched type results in empty columns
- **Inconsistent visual treatment** - Master and detail tables with different heights or density settings look disconnected

## Related Patterns

- **Lifecycle Status Split** - Pair of tables showing active vs. inactive items
- **Dashboard Context Scoping** - All widgets on a dashboard filtering relative to the dashboard page's attributes
- **Hierarchical Drill-Down** - Cascading master-detail through multiple levels