@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-platform-embeddedSearchAsTable/research.md

@@ -0,0 +1,428 @@
+# Research: cf.platform.embeddedSearchAsTable Widget
+
+## Widget Overview
+
+**Widget ID:** `cf.platform.embeddedSearchAsTable`
+**Repository:** main (cf.cplace.platform)
+**Icon:** `fa-table`
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/EmbeddedSearchAsTableWidgetDefinition.java`
+
+## 1. Purpose
+
+### Short Description
+The Embedded Search As Table widget displays search results in a configurable, interactive table format with sorting, filtering, grouping, and pagination capabilities.
+
+### Detailed Description
+This widget executes a user-defined search query and presents the results in a table view. It extends the generic search-as-table functionality to provide a flexible, embeddable component for displaying collections of entities. The widget supports advanced table features including multi-column sorting, column visibility configuration, row grouping, pre-set filters, and table linking (where one table's selection can filter another table's results). It serves as a versatile data display component that can be customized for various use cases without requiring custom code.
+
+The widget is built on top of the `GenericSearchAsTableWidgetDefinition` base class and uses the `EmbeddedSearchReportTableSpecificationHandler` to process configuration and render the table. It implements the `SingleSelectionWidget` interface, enabling it to interact with other widgets on the same page through selection-based filtering.
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+1. **Display Related Entities**
+   - **Scenario:** A Project page displays all Tasks belonging to that project in a table
+   - **Benefit:** Users see related entities organized in a structured, filterable table without writing custom code
+   - **User Action:** Configure a search filtering for entities with specific relationships, add table to page layout
+   - **Example Configuration:** Search for Tasks where `project` attribute equals current page
+
+2. **Hierarchical Data Views**
+   - **Scenario:** A Department page shows all Employees in that department, grouped by role
+   - **Benefit:** Complex hierarchical relationships are visualized with grouping and sorting
+   - **User Action:** Configure search, set GROUP_COLUMN to "role", enable sorting by seniority
+   - **Example Configuration:** Search Department employees, group by role, sort by hire date
+
+3. **Dashboard Summary Tables**
+   - **Scenario:** A dashboard page displays key metrics and entity lists across multiple tables
+   - **Benefit:** Multiple data views consolidated on a single page with consistent table interface
+   - **User Action:** Add multiple Embedded Search As Table widgets with different searches to a dashboard
+   - **Example Configuration:** One table for "Open Issues", another for "Recent Updates", third for "Overdue Tasks"
+
+4. **Master-Detail Relationship Display**
+   - **Scenario:** A Configuration page shows Settings in one table, and selecting a Setting displays its Values in a second connected table
+   - **Benefit:** Linked tables provide drill-down navigation without page transitions
+   - **User Action:** Configure first table, add second table with CONNECTED_TABLE_WIDGET_ID pointing to first table
+   - **Example Configuration:** Settings table (master), Values table filtered by selected Setting (detail)
+
+5. **Filtered Entity Collections**
+   - **Scenario:** Display all Products launched in Q1 2025 with specific attributes visible
+   - **Benefit:** Pre-configured views save users from repeatedly building the same search
+   - **User Action:** Define search with type and attribute filters, configure visible columns
+   - **Example Configuration:** Search for Products, filter by launchDate in date range, show only name, status, revenue columns
+
+6. **Cross-Workspace Entity Lists**
+   - **Scenario:** A Portfolio page in one workspace displays Projects from multiple workspaces
+   - **Benefit:** Aggregated view across workspace boundaries for enterprise-wide visibility
+   - **User Action:** Configure search with SpaceFilter including multiple workspace IDs
+   - **Example Configuration:** Search for Projects in spaces ["Portfolio A", "Portfolio B", "Portfolio C"]
+
+7. **Compact Entity Lists**
+   - **Scenario:** Display a large number of entities in limited vertical space using single-spaced rows
+   - **Benefit:** More information visible without scrolling, optimized for space-constrained layouts
+   - **User Action:** Enable SINGLE_SPACED configuration option
+   - **Example Configuration:** Task list with SINGLE_SPACED=true for compact display
+
+8. **Read-Only Data Views**
+   - **Scenario:** Display reference data or archived entities without allowing creation of new items
+   - **Benefit:** Prevents accidental creation of entities in reference data collections
+   - **User Action:** Set ALLOW_NEW="No" to hide the "New" button
+   - **Example Configuration:** Display archived projects with ALLOW_NEW=false
+
+9. **Entity Lists for Reports**
+   - **Scenario:** Generate a printable or exportable view of entities without table chrome
+   - **Benefit:** Clean output suitable for reports and exports
+   - **User Action:** Disable SHOW_TABLE_HEADER, SHOW_TABLE_FOOTER, HIDE_TABLE_LINKS, SHOW_TABLE_ACTIONS
+   - **Example Configuration:** Employee roster with minimal UI for PDF export
+
+### When to Use This Widget
+
+**Use this widget when:**
+- You need to display a collection of entities based on a search query
+- You want table features like sorting, filtering, grouping, and pagination
+- You need to show related entities on a detail page
+- You want to create dashboard-style views with multiple data tables
+- You need master-detail relationships between tables
+- You want users to interact with tabular data (sorting, filtering) without custom code
+- You need to aggregate entities from multiple workspaces
+
+**Do NOT use this widget when:**
+- You only need to display a simple list without table features (use `cf.platform.embeddedSearchAsList` instead)
+- You need a highly customized table with specialized interactions (consider a custom widget)
+- You're displaying a single entity's attributes (use attribute widgets instead)
+- You need real-time collaborative editing of table data (this is a read-display widget)
+- You need pivot tables, advanced analytics, or business intelligence features (consider visualization widgets)
+
+### Relationship to Similar Widgets
+
+**vs. `cf.platform.embeddedSearchAsList`:**
+- EmbeddedSearchAsList displays results as a simple bulleted list
+- EmbeddedSearchAsTable provides table features: columns, sorting, filtering, grouping
+- Use List for simpler displays, Table for structured data requiring column organization
+
+**vs. `cf.platform.tableWidget`:**
+- TableWidget is for attribute-specific tabular displays on entity pages
+- EmbeddedSearchAsTable is search-based and can aggregate from multiple sources
+- Use TableWidget for single-entity attribute collections, EmbeddedSearchAsTable for search results
+
+**vs. Custom Widgets (e.g., Gantt, Board):**
+- Custom widgets provide specialized visualizations (timeline, kanban)
+- EmbeddedSearchAsTable provides standard tabular data display
+- Use custom widgets for domain-specific visualizations, EmbeddedSearchAsTable for general tables
+
+## 3. Configuration Concepts
+
+### High-Level Configuration Areas
+
+The widget exposes 19 configuration parameters organized into several functional areas:
+
+#### A. Search Definition (Required)
+**Core Concept:** Defines which entities to display in the table
+
+- **SEARCH** (required): JSON representation of the search query
+  - Defines entity types, filters, and search criteria
+  - Can include complex filters: type filters, space filters, attribute filters, sub-searches
+  - Example: Search for "Tasks" where "status" equals "Open" in current workspace
+  - Validation: Ensures search is syntactically valid and filters are compatible
+
+#### B. Display Configuration
+**Core Concept:** Controls the visual appearance and available UI elements
+
+- **LOCALIZED_TITLE**: Custom title displayed in widget header (defaults to human-readable search description)
+- **HEIGHT**: Fixed pixel height (auto-height if not specified)
+- **SINGLE_SPACED**: Compact row display (true/false, default: false)
+- **SHOW_TABLE_ACTIONS**: Show/hide toolbar with buttons (true/false, default: true)
+- **SHOW_TABLE_HEADER**: Show/hide column headers (true/false, default: true)
+- **SHOW_TABLE_FOOTER**: Show/hide pagination footer (true/false, default: true)
+- **HIDE_TABLE_LINKS**: Remove hyperlinks from entity names (true/false, default: false)
+- **HIDE_NAMES**: Hide entity name column entirely (true/false, default: false)
+- **ALLOW_NEW**: Show/hide "New" button for creating entities (Yes/No, default: Yes)
+
+#### C. Column Configuration
+**Core Concept:** Determines which attributes are displayed as table columns
+
+- **COLUMNS**: JSON array defining column visibility and order
+  - Format: `[{"name": "attributeName", "visible": true/false}, ...]`
+  - Controls which entity attributes appear as columns
+  - Determines column order from left to right
+  - Example: Display only "name", "status", "dueDate" attributes
+
+#### D. Filtering
+**Core Concept:** Pre-configured filters that users can apply/remove interactively
+
+- **FILTERS**: JSON array of pre-set column filters
+  - Different from SEARCH filters (which are permanent)
+  - Users can toggle these on/off in the table UI
+  - Example: Pre-define a filter for "status = Open" that users can enable/disable
+
+#### E. Sorting
+**Core Concept:** Default sort order when table is first displayed
+
+- **MULTI_SORT_COLUMNS**: JSON array for multi-column sorting (introduced in v4.50)
+  - Format: `[{"sortColumn": "attr1", "sortOrder": "asc/desc", "sortingPriorityIndex": 1}, ...]`
+  - Supports sorting by multiple columns with priority order
+  - Example: Sort by "priority" descending, then by "dueDate" ascending
+- **SORT_COLUMN** (legacy): Single column name for sorting
+- **SORT_ORDER** (legacy): "Aufsteigend" (ascending) or "Absteigend" (descending)
+  - Legacy parameters are automatically migrated to MULTI_SORT_COLUMNS
+
+#### F. Grouping
+**Core Concept:** Organize rows into collapsible groups based on attribute values
+
+- **GROUP_COLUMN**: Attribute name to group rows by
+  - Example: Group tasks by "assignee" to see all tasks per person
+  - Rows with the same attribute value are grouped together
+  - Groups are collapsible/expandable in the UI
+- **GROUP_ORDER**: Sort order for groups ("asc" or "desc", default: "asc")
+  - Controls the order in which groups appear
+
+#### G. Table Linking
+**Core Concept:** Connect multiple tables so selection in one filters another
+
+- **CONNECTED_TABLE_WIDGET_ID**: Widget ID of another table on the same page
+  - When a row is selected in the connected table, this table's search is filtered
+  - Enables master-detail relationships
+  - Example: Selecting a Project in table A shows only its Tasks in table B
+  - Validation: Ensures the referenced widget exists on the page
+
+### Configuration Modes and Patterns
+
+**Simple Display Mode:**
+- Configure only SEARCH and COLUMNS
+- Use default values for all display options
+- Best for straightforward entity lists
+
+**Dashboard Mode:**
+- Multiple widgets on one page
+- Custom LOCALIZED_TITLE for each
+- Specific column configurations per widget
+- ALLOW_NEW="No" for read-only views
+
+**Master-Detail Mode:**
+- Two or more widgets with CONNECTED_TABLE_WIDGET_ID
+- Parent table: standard configuration
+- Child table: references parent via CONNECTED_TABLE_WIDGET_ID
+- Child search includes filter based on parent selection
+
+**Compact Mode:**
+- SINGLE_SPACED=true for dense display
+- Reduced HEIGHT for space-constrained layouts
+- SHOW_TABLE_FOOTER=false to save vertical space
+
+**Report Mode:**
+- SHOW_TABLE_ACTIONS=false (no toolbar)
+- SHOW_TABLE_FOOTER=false (no pagination)
+- HIDE_TABLE_LINKS=true (no clickable elements)
+- Clean output suitable for printing/exporting
+
+### Migration and Backward Compatibility
+
+The widget includes automatic migration support:
+
+1. **Title Migration:**
+   - Old: TITLE (unlocalized string)
+   - New: LOCALIZED_TITLE (localized string)
+   - Migration: Automatically converts on widget load
+
+2. **Sort Migration (v4.50):**
+   - Old: SORT_COLUMN + SORT_ORDER (single column)
+   - New: MULTI_SORT_COLUMNS (multi-column)
+   - Migration: Automatically converts legacy sort to multi-sort format
+
+### Validation
+
+The widget includes two custom validators:
+
+1. **TableSearchValidator:**
+   - Validates SEARCH parameter syntax
+   - Traverses complex filter trees (AND, OR, NOT filters)
+   - Ensures elementary filters are compatible with search context
+   - Returns detailed error messages for invalid searches
+
+2. **ConnectedTableValidator:**
+   - Validates CONNECTED_TABLE_WIDGET_ID references
+   - Ensures referenced widget exists on the same page
+   - Prevents broken table links
+
+## 4. Related Features and Context
+
+### Parent Architecture
+
+**Base Class:** `GenericSearchAsTableWidgetDefinition`
+- Abstract base for all search-based table widgets
+- Provides template method pattern for table rendering
+- Delegates to `GenericSearchAsTableSpecificationHandler` for table configuration
+- Enforces consistent table UI across different search table widgets
+
+**Handler:** `EmbeddedSearchReportTableSpecificationHandler`
+- Processes widget configuration parameters
+- Constructs the Search object with sorting and filtering
+- Implements table controller interface for persistence of user preferences
+- Handles connected table search context
+
+### Widget Family
+
+This widget is part of the platform's search-based display widgets:
+
+- **cf.platform.embeddedSearchAsTable** (this widget): Table view with advanced features
+- **cf.platform.embeddedSearchAsList**: Simple list view
+- **cf.cplace.platform.tableWidget**: Attribute-specific table widget
+
+### Technical Dependencies
+
+- **Search Framework:** Uses `cf.cplace.platform.core.datamodel.search.Search` for querying
+- **FlexiGrid Components:** Built on platform's table rendering infrastructure
+- **SingleSelectionWidget Interface:** Enables inter-widget communication for table linking
+- **Widget Configuration System:** Leverages platform's widget asset management
+
+### Data Model Integration
+
+- Works with any custom entity type that supports search
+- Respects access restrictions and permissions (users only see entities they can read)
+- Supports all standard search filter types (type, space, attribute, sub-search filters)
+- Integrates with custom reference attributes for relationship navigation
+
+## 5. Code References
+
+### Primary Files
+
+| File | Path | Purpose |
+|------|------|---------|
+| Widget Definition | `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/EmbeddedSearchAsTableWidgetDefinition.java` | Main widget class with validators and migration logic |
+| Configuration Type | `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/templating/WidgetTypes.java:220-343` | EMBEDDED_SEARCH_AS_TABLE type definition and parameters |
+| Base Class | `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/GenericSearchAsTableWidgetDefinition.java` | Abstract parent class for search table widgets |
+| Handler | `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/functions/EmbeddedSearchReportTableSpecificationHandler.java` | Configuration processor and table controller |
+
+### Mixin Definitions
+
+| Mixin | Path | Attributes Provided |
+|-------|------|-------------------|
+| BASE_MIXIN | `WidgetTypes.java:49-73` | TITLE, COMPULSORY_TITLE, HEIGHT |
+| SEARCH_MIXIN | `WidgetTypes.java:76-130` | SEARCH, SORT_COLUMN, SORT_ORDER, MULTI_SORT_COLUMNS |
+| SEARCH_AS_TABLE_MIXIN | `WidgetTypes.java:133-181` | COLUMNS, FILTERS, GROUP_COLUMN, GROUP_ORDER |
+
+### Test Files
+
+| Test | Path | Coverage |
+|------|------|----------|
+| Search Import | `cf.cplace.platform/src/test/java/cf/cplace/platform/inout/xml/TestImportWithSearchInWidgets.java` | Validates search resolution during import/export |
+| Search References | `cf.cplace.platform/src/test/java/cf/cplace/platform/inout/xml/TestImportWithSearchReferences.java` | Tests reference resolution in searches |
+
+## 6. Key Implementation Details
+
+### Widget Kind Registration
+- Widget ID: `cf.platform.embeddedSearchAsTable`
+- Registered in: `PlatformWidgetDefinitions.java`
+- Icon: Font Awesome `fa-table`
+
+### Configuration Type Structure
+```java
+TypeDef TYPE = new TypeDef(
+    "cf.platform.embeddedSearchAsTable",
+    SEARCH,                    // Required
+    LOCALIZED_TITLE,           // Optional
+    COLUMNS,                   // Optional
+    FILTERS,                   // Optional
+    CONNECTED_TABLE_WIDGET_ID, // Optional
+    SINGLE_SPACED,             // Optional (default: false)
+    SHOW_TABLE_ACTIONS,        // Optional (default: true)
+    SHOW_TABLE_HEADER,         // Optional (default: true)
+    SHOW_TABLE_FOOTER,         // Optional (default: true)
+    HIDE_TABLE_LINKS,          // Optional (default: false)
+    HIDE_NAMES,                // Optional (default: false)
+    MULTI_SORT_COLUMNS,        // Optional
+    GROUP_COLUMN,              // Optional
+    GROUP_ORDER,               // Required (default: "asc")
+    ALLOW_NEW,                 // Required (default: "Yes")
+    HEIGHT                     // Optional
+);
+```
+
+### Search Construction Process
+1. Widget configuration contains SEARCH as JSON string
+2. `getSearchFromWidgetConfiguration()` parses JSON to Search object
+3. Sorting criteria (MULTI_SORT_COLUMNS or legacy SORT_COLUMN/SORT_ORDER) are applied
+4. Connected table search context is set if CONNECTED_TABLE_WIDGET_ID is configured
+5. Resulting Search object is passed to handler for execution
+
+### Table Rendering Flow
+1. `getContentSubstitution()` is called by widget framework
+2. Creates `EmbeddedSearchReportTableSpecificationHandler` with configuration
+3. Handler constructs Search from configuration
+4. Search is executed, returning SearchResult
+5. `CustomSearchResultTable` renders HTML table from SearchResult
+6. Template substitution injects table HTML into widget container
+
+## 7. Architecture Patterns
+
+### Mixin Composition Pattern
+- Reusable attribute definitions in BASE_MIXIN, SEARCH_MIXIN, SEARCH_AS_TABLE_MIXIN
+- Widget type copies needed attributes from mixins
+- Promotes consistency across related widget types
+- Enables shared configuration UI components
+
+### Template Method Pattern
+- `GenericSearchAsTableWidgetDefinition.getContentSubstitution()` is final
+- Calls abstract methods: `getWidgetTitle()`, `createTableSpecificationHandler()`
+- Subclasses customize behavior without changing rendering flow
+- Ensures consistent table widget architecture
+
+### Strategy Pattern
+- `GenericSearchAsTableSpecificationHandler` interface defines table configuration strategy
+- `EmbeddedSearchReportTableSpecificationHandler` implements strategy for this widget
+- Different table widgets can provide different handler implementations
+- Enables flexible table configuration while reusing rendering infrastructure
+
+### Validator Extension Pattern
+- `TableSearchValidator` and `ConnectedTableValidator` extend `CustomValidatorForWidgetExtension`
+- Validators are registered for specific widget type + attribute combinations
+- Enables context-aware validation tied to widget configuration
+- Validation errors are displayed in widget configuration UI
+
+## 8. Related Research
+
+- **Parameter Details:** `/Users/thomasbuechner/dev/repos/main/specs/2026-01-11_embedded-search-as-table-widget-parameters/research.md` - Comprehensive analysis of all 19 configuration parameters
+- **Search Semantics:** `/Users/thomasbuechner/dev/repos/main/specs/2026-01-09_widget-search-query/research.md` - Details on search query structure
+- **Single Selection:** `/Users/thomasbuechner/dev/repos/main/specs/2026-01-11_connected-single-attribute-widget-parameters/singleSelectionWidgetId-semantics.md` - Semantics of widget linking via SingleSelectionWidget interface
+
+## 9. Open Questions
+
+1. **Performance Considerations:**
+   - What are the recommended limits for search result size?
+   - How does pagination affect performance with large result sets?
+   - Are there best practices for optimizing complex searches in widgets?
+
+2. **Advanced Scenarios:**
+   - Can CONNECTED_TABLE_WIDGET_ID create circular dependencies?
+   - How many levels of table linking are practical?
+   - What happens when connected table search returns no results?
+
+3. **Customization Boundaries:**
+   - Can column rendering be customized without creating a custom widget?
+   - Are there hooks for adding custom actions to table rows?
+   - Can table export formats be extended?
+
+4. **Migration Edge Cases:**
+   - What happens if both legacy sort parameters and MULTI_SORT_COLUMNS are present?
+   - Are there scenarios where automatic migration might fail?
+   - How are conflicting configurations handled during migration?
+
+## 10. Summary
+
+The `cf.platform.embeddedSearchAsTable` widget is a versatile, search-driven table component that provides a rich set of configuration options for displaying entity collections. It serves as the primary mechanism for embedding tabular data views in cplace pages without requiring custom development. The widget supports advanced table features including multi-column sorting, grouping, filtering, and table linking, making it suitable for a wide range of use cases from simple entity lists to complex dashboard layouts with master-detail relationships.
+
+Key strengths include:
+- **Configuration-driven:** No code required for most use cases
+- **Feature-rich:** Comprehensive table functionality out of the box
+- **Extensible:** Mixin-based architecture enables reuse and consistency
+- **Validated:** Strong validation ensures configuration integrity
+- **Migratable:** Automatic migration supports backward compatibility
+
+The widget is particularly well-suited for:
+- Displaying related entities on detail pages
+- Creating dashboard-style multi-table views
+- Implementing master-detail table relationships
+- Providing filtered, sorted, grouped views of entity collections
+- Building read-only reference data displays
+
+When combined with cplace's search framework and widget linking capabilities, this widget enables sophisticated data presentation patterns without custom widget development.

package/dist/widget-specifications/_research_from_ga_products/cf-platform-files/research.md

@@ -0,0 +1,240 @@
+# Files Widget Research
+
+**Widget ID:** `cf.platform.files`
+**Definition Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/FilesWidgetDefinition.java`
+**Handler Class:** `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/document/FilesWidgetHandler.java`
+
+## Purpose
+
+The Files widget provides a file management interface that allows users to upload files to a page and displays all attachments in a sortable table format.
+
+## Description
+
+The Files widget displays a table of file attachments with drag-and-drop upload functionality. Users can view file metadata (name, type, size, last modification date, and last editor) and upload new files directly through the widget interface.
+
+## Core Functionality
+
+### File Display
+- Displays files in a sortable table with the following columns:
+  - Name (with clickable link)
+  - Type
+  - Size
+  - Last Modification date
+  - Last Editor
+- Supports file version badges with links to version history
+- Implements client-side sorting with configurable default sort column and order
+
+### File Upload
+- Drag-and-drop file upload interface
+- Visual upload progress indicator with percentage
+- Upload zone displayed only when user has permission to create documents
+- Files can be attached either:
+  - Directly to the embedding page (default)
+  - To a specific reference attribute configured in the widget
+
+### File Attachment Modes
+
+The widget supports two distinct attachment modes:
+
+1. **Direct Page Attachment** (Default)
+   - Files are attached as direct children of the page
+   - Uses the page's standard document collection
+   - No reference attribute configuration needed
+
+2. **Reference Attribute Attachment**
+   - Files are attached to a specific reference attribute on the page
+   - Attribute must be a reference to Document type
+   - Supports both single-value and multi-value reference attributes
+   - Only shows files attached to that specific attribute
+
+### Connected Widget Mode
+
+The widget can be connected to a table widget to provide context-specific file management:
+- When connected, the widget waits for item selection in the table
+- Files are managed in the context of the selected table item
+- Displays "Please select an item in the table" message when no item is selected
+- The reference attribute enumeration is filtered based on the table widget's search configuration
+
+## Use Cases
+
+### 1. General Document Management
+**When to use:** You want to provide a simple way for users to attach and manage files on any page.
+
+**Example:** A project page where team members can upload project documents, reports, and presentations.
+
+**Configuration:**
+- Embed widget on a page
+- Leave reference attribute empty
+- Files attach directly to the page
+
+### 2. Structured File Organization
+**When to use:** You need files attached to specific attributes for structured data management or reporting.
+
+**Example:** A product page with separate file collections for "Technical Specifications", "Marketing Materials", and "User Manuals", each represented by a different reference attribute.
+
+**Configuration:**
+- Create reference attributes of type "File" with appropriate multiplicities
+- Configure separate Files widgets for each attribute
+- Each widget shows only files attached to its configured attribute
+
+### 3. Context-Sensitive File Management
+**When to use:** You need to manage files in the context of items displayed in a table.
+
+**Example:** A task list table where selecting a task shows and allows managing files specific to that task.
+
+**Configuration:**
+- Create a table widget showing related items
+- Connect the Files widget to the table widget
+- Files are managed in the context of the selected table item
+
+### 4. Custom File Collections
+**When to use:** You want to categorize files or enforce specific file management rules.
+
+**Example:** A compliance page with separate sections for "Required Documents" (single-value) and "Supporting Evidence" (multi-value).
+
+**Configuration:**
+- Create single-value reference attribute for required documents
+- Create multi-value reference attribute for supporting documents
+- Configure separate Files widgets for each
+
+## Configuration Options
+
+### Title
+- **Type:** Localized String (optional)
+- **Purpose:** Custom title for the widget
+- **Default:** Widget displays without a custom title
+
+### Reference Attribute
+- **Type:** String (dynamic enumeration)
+- **Purpose:** Specifies which attribute to attach files to
+- **Constraints:**
+  - Must be a reference attribute to Document type
+  - Must reference documents in the same workspace
+  - Only attributes with "Any number of values" multiplicity are selectable by default
+  - If left empty, files attach directly to the embedding page
+- **Validation:** System validates that the selected attribute is a valid Document reference
+- **Help Text:** "Selectable attributes are references with multiplicity 'Any number of values' to files in this workspace."
+
+### Table Widget ID
+- **Type:** String (optional)
+- **Purpose:** Connects this Files widget to a table widget for context-sensitive file management
+- **Behavior:**
+  - When set, the widget waits for item selection in the connected table
+  - Files are managed in the context of the selected item
+  - Reference attribute options are filtered based on the table's search configuration
+
+### Sort Column
+- **Type:** Enumeration
+- **Options:**
+  - Name (default)
+  - File Size
+  - Last Modification
+  - Last Editor
+- **Purpose:** Determines the default sort column for the file table
+
+### Sort Order
+- **Type:** Enumeration
+- **Options:**
+  - Ascending (default)
+  - Descending
+- **Purpose:** Determines the default sort order for the file table
+
+### Height
+- **Type:** Number (optional)
+- **Purpose:** Fixed height for the widget in pixels
+- **Behavior:** Inherited from BASE_MIXIN height attribute
+
+## Technical Details
+
+### Embedding Requirements
+- Can only be embedded on Pages
+- Must be embedded as a widget (not inline)
+- Respects page-level permissions for document creation
+- Uses the `fa-upload` icon in the widget palette
+
+### Permission Handling
+- Upload functionality is only shown if user has `mayCreateDocument()` permission
+- Permission is checked at the page level (for the embedding page or selected page)
+- Read-only pages prevent document creation
+
+### File Reference Attachment
+The widget implements special logic for attaching files to reference attributes:
+- Detects whether the reference attribute is single-value or multi-value
+- For single-value: Replaces the existing reference
+- For multi-value: Adds to the existing collection (no duplicates)
+- Updates are performed on writable copies of the page entity
+
+### Attribute Enumeration
+The widget provides dynamic enumeration of valid reference attributes:
+- Filters attributes to only show Document references
+- Respects same-workspace constraints
+- When connected to a table widget, filters based on all type definitions in the table's search
+- Groups attributes by name when multiple type definitions are involved
+
+### Frontend Integration
+- Uses AngularJS controller `FileUploadCtrl` for upload handling
+- Implements real-time upload progress tracking
+- Uses the `cplace-static-table` directive for table rendering
+- Supports custom column sorting types (file-size, modified date)
+- Provides action buttons and multi-delete functionality
+
+## Related Components
+
+### Handlers
+- **FilesWidgetHandler:** Main handler for rendering widget content and handling state
+- **NewDocumentHandler:** Creates new document entities for upload
+- **UploadHandler:** Handles the actual file upload process
+- **FilesButtonsHandler:** Provides action buttons for file operations
+
+### Type Definitions Referenced
+- **Document:** The entity type for uploaded files
+- **Page:** The embedding entity for the widget
+- **WidgetConfiguration:** Stores widget configuration settings
+
+### Validators
+- **FileReferenceAttributeValidator:** Validates that the reference attribute:
+  - Points to Document type (not other entity types)
+  - Exists in the type definition
+  - Is present in all type definitions when table widget is connected
+
+## Integration Points
+
+### With Table Widget
+- Can be connected via `TABLE_WIDGET_ID` configuration
+- Shares state through the connected table's selection
+- Filters available attributes based on the table's search type definitions
+
+### With Document Management System
+- Integrates with the platform's document versioning system
+- Shows version badges with links to version history
+- Respects document permissions and access controls
+
+### With Custom Attributes
+- Works with any reference attribute pointing to Documents
+- Supports both single and multi-valued references
+- Validates attribute types at configuration time
+
+## Localization
+
+The widget is fully localized with messages for:
+- Widget name: "Files"
+- Widget description: "Allows you to upload files to the page and lists all attachments in a table."
+- UI labels: Name, Type, Size, Last Modification, Last Editor
+- Upload messages: "Drop Files here", "Uploading..."
+- Validation messages: "Invalid value: attribute type must be File"
+- Help text for configuration options
+
+## Key Code Locations
+
+- **Definition:** `/cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/FilesWidgetDefinition.java:59`
+- **Handler:** `/cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/handler/document/FilesWidgetHandler.java:46`
+- **Template:** `/cf.cplace.platform/src/main/resources/cf/cplace/platform/frontend/handler/document/filesWidget.htm:1`
+- **Configuration Type:** Referenced in `WidgetTypes.FILES_WIDGET` at line 440
+- **Localization:** `/cf.cplace.platform/src/main/resources/cf/cplace/platform/messages_en.properties` (search for "filesWidget")
+
+## Widget Characteristics
+
+- **No Padding:** The widget renders with no padding (`isNoPadding() = true`)
+- **Icon:** Uses `fa-upload` font-awesome icon
+- **App:** Part of the Platform app (`PlatformPlugin.INSTANCE().platformApp`)
+- **Kind:** `cf.platform.files`