## Overview

The Tuple widget shows the tuple pages within a table. It provides a specialized table view for managing collections of referenced pages (called "tuples") through a multi-reference attribute. It combines viewing, inline editing, and CRUD operations in a spreadsheet-like interface without requiring users to navigate away from the parent page.

In cplace terminology, "tuples" are referenced entities (pages) linked to the current page through a reference attribute. This widget displays these referenced pages with configurable columns showing selected attributes from the referenced type.

## Use Cases

### Master-Detail Relationships
Display and manage a list of related detail records for a master record.
- **Example**: A project page showing related tasks, risks, or milestones
- **Example**: A customer page displaying contacts or orders
- **Benefit**: All related items visible and editable in one place

### Structured Data Collections
Manage collections of structured data entries where multiple attributes of each item need to be visible.
- **Example**: Configuration items, checklist entries, or requirements
- **Benefit**: Table format provides quick scanning of multiple data points per item

### Editable Reference Lists
When users need to create, edit, and delete referenced items directly from the parent page.
- **Benefit**: Inline editing without navigation
- **Benefit**: Quick creation of new related entities
- **Benefit**: Integrated deletion with confirmation

### Ordered Collections
When the sequence of referenced items matters and users need to reorder them.
- **Feature**: Drag-and-drop reordering
- **Feature**: Manual ordering controls (up/down buttons)
- **Benefit**: Maintains user-defined sequence in the reference attribute

### Configurable Views of Related Data
Show only specific attributes of referenced items tailored to the use case.
- **Feature**: Custom column selection from available tuple attributes
- **Benefit**: Focused view without information overload
- **Benefit**: Adapts to different viewing contexts

## Operating Modes

The widget has two mutually exclusive ordering modes:

### Manual Ordering Mode
**Enabled when**: Reordering is allowed AND no sort attribute is configured

Users can drag-and-drop or use up/down buttons to reorder tuples. The order is persisted in the reference attribute and maintained across sessions.

**Requirements**:
- User must have edit permission on the tuple attribute
- At least 2 tuples must exist
- Automatic sorting must not be configured

### Automatic Sorting Mode
**Enabled when**: A sort attribute is configured

Tuples are automatically sorted by the specified attribute in ascending or descending order. Users cannot manually change the order.

**Note**: This mode and manual ordering mode cannot be used together.

## Design Considerations

### When to Use This Widget

**Choose Tuples Widget when**:
- You need to manage a moderate collection of referenced entities (typically < 100 items)
- Users need inline editing capabilities for referenced items
- The relationship is managed through a reference attribute on the embedding page
- CRUD operations on referenced items are important to the workflow
- Column-based view of multiple attributes is valuable

**Consider Alternatives when**:
- You need complex filtering or aggregation (use Embedded Search Table)
- The collection is very large (> 100 items) (use Embedded Search Table)
- You only need read-only display (use Table Widget or Embedded Search)
- The relationship is single-valued 1-to-1 (use Connected Attributes Group)
- You need cross-workspace searches (use Embedded Search)

### Permission-Aware Design

The widget adapts its UI based on user permissions and configuration:

1. **Allow Reordering**: Shows/hides ordering controls based on configuration and permissions
2. **Allow Adding**: Shows/hides "Create [Type]" button based on create permissions and multiplicity
3. **Allow Editing**: Enables/disables inline editing based on edit permissions
4. **Allow Deleting**: Shows/hides delete buttons based on delete permissions

This granular control allows precise definition of user capabilities at the widget level.

### Configuration Dependencies

Key configuration flow:
1. First select the reference attribute (Tuple Attribute)
2. Save configuration to refresh available options
3. Then select which tuple attributes to display as columns
4. Configure ordering mode (manual OR automatic, not both)
5. Set permission toggles based on intended user interaction

**Important**: The list of available tuple attributes for column selection only becomes available after selecting and saving the reference attribute.

## Common Pitfalls

### Trying to Use Both Ordering Modes
**Problem**: Configuring both manual reordering and automatic sorting simultaneously.

**Solution**: Choose one mode. If sorting is needed, use automatic sorting. If user-defined order is needed, enable manual reordering without configuring a sort attribute.

### Not Saving After Selecting Reference Attribute
**Problem**: Attempting to configure visible columns before saving the reference attribute selection.

**Solution**: Save the widget configuration after selecting the tuple attribute to refresh the available column options.

### Using for Large Collections
**Problem**: Performance issues when displaying hundreds of tuples.

**Solution**: For large collections, use Embedded Search Table widget which provides pagination and is optimized for larger datasets.

### Insufficient Permissions
**Problem**: Users cannot perform expected operations (create, edit, delete, reorder).

**Solution**: Verify users have:
- Edit permission on the reference attribute (for add/remove/reorder)
- Create permission on tuple type (for adding)
- Edit permission on individual tuples (for inline editing)
- Delete permission on individual tuples (for deletion)

### Overlooking Multiplicity Constraints
**Problem**: Users cannot add tuples when maximum multiplicity is reached.

**Solution**: Check the reference attribute's multiplicity settings. If set to single-valued or has a maximum, the widget will prevent additional additions.

## Related Widgets

### Connected Attributes Group (`cf.cplace.platform.connectedAttributesGroup`)
Shows attributes of a single referenced entity in form layout.

**Use Connected Attributes when**: You have a 1-to-1 relationship and need to display/edit attributes of a single referenced page.

**Use Tuples Widget when**: You have a 1-to-many relationship and need table-based view of multiple referenced pages.

### Embedded Search Table (`cf.platform.embeddedSearchAsTable`)
Shows search results in table format with advanced filtering and aggregation.

**Use Embedded Search when**: You need complex filtering, large datasets, cross-space searches, aggregations, or read-only display of query results.

**Use Tuples Widget when**: You need CRUD operations, inline editing, manual ordering, or direct reference management through an attribute.

### Table Widget (`cf.cplace.platform.tableWidget`)
Generic table for displaying structured data.

**Use Table Widget when**: You need a simple read-only table display of data.

**Use Tuples Widget when**: You need interactive management of referenced entities with editing and CRUD capabilities.

### Table Detail View Widget (`cf.cplace.tableDetailViewWidget.widget`)
Shows table with expandable detail panels.

**Use Table Detail View when**: You need master-detail layout with expandable detail panels showing more information than fits in columns.

**Use Tuples Widget when**: You need simpler table-based reference management without detail panels.

## Key Differences from Similar Widgets

### vs. Embedded Search Table
- **Tuples Widget**: Direct reference management, inline editing, CRUD operations, manual ordering, works through reference attribute
- **Embedded Search**: Read-only view, complex filtering, cross-space searches, aggregations, pagination for large datasets

### vs. Connected Attributes Group
- **Tuples Widget**: Multiple referenced entities in table format
- **Connected Attributes**: Single referenced entity with form layout

### vs. Table Detail View
- **Tuples Widget**: Simpler table-focused interface with inline editing
- **Table Detail View**: More complex layout with expandable detail views

## Prerequisites

### Data Model Requirements
1. A reference attribute must exist on the embedding page's type
2. The reference attribute must point to a specific tuple type
3. The tuple type should have attributes that make sense to display in columns
4. Multi-value multiplicity (0..* or similar) for the reference attribute

### Permission Requirements
1. Read access to the tuple type and its attributes
2. Edit access to the reference attribute (for add/remove/reorder operations)
3. Create permissions on tuple type (for creation operations)
4. Delete permissions on tuple type (for deletion operations)

### Embedding Context
The widget must be embedded in a Page or TypeDefinition. It cannot be embedded in other contexts.

## Extension Points

The widget provides several extension points for custom behavior:

### AssignReferenceToNewTupleExtension
Add custom search filters when creating new tuples to restrict which tuples can be created based on business logic.

### TupleValidationErrorExtension
Show custom error messages or warnings about the tuple collection in the widget UI.

### PreventRemoveTupleExtension
Prevent deletion of specific tuples to protect required tuples or enforce business rules.