@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,485 @@
+# Research: cf.platform.embeddedSearchAsList Widget
+
+**Widget ID**: `cf.platform.embeddedSearchAsList`
+**Repository**: main
+**Definition Class**: `cf.cplace.platform/src/main/java/cf/cplace/platform/frontend/widgets/EmbeddedSearchAsListWidgetDefinition.java`
+**Date**: 2026-01-16
+
+---
+
+## 1. Widget Description
+
+The **Embedded Search as List** widget generates a simple list of search results displayed as clickable links, sorted alphabetically by default.
+
+It executes a configured search query and displays the results as an unordered HTML list (ul/li), with each search result rendered as a link to the corresponding page.
+
+---
+
+## 2. Purpose and Core Functionality
+
+### What This Widget Does
+
+The `cf.platform.embeddedSearchAsList` widget:
+
+1. **Executes a search query** - Runs a configured search against the cplace data model
+2. **Renders results as a list** - Displays results as a simple unordered list with clickable links
+3. **Provides pagination feedback** - Shows when results are truncated (displays first 1000 results maximum)
+4. **Handles empty results** - Shows a "No results" message when the search returns nothing
+5. **Supports custom sorting** - Can sort by a specific attribute in ascending or descending order
+6. **Falls back to alphabetical sorting** - Automatically sorts alphabetically if no custom sort is specified and no text search is used
+
+### Key Characteristics
+
+- **Simple presentation**: Basic list format without table columns or advanced formatting
+- **Lightweight**: Minimal configuration compared to table-based widgets
+- **Embedded widget**: Designed to be embedded in pages, layouts, or rich text attributes
+- **Search-driven**: All content is dynamically generated from search results
+- **Result limit**: Returns up to 1000 results (first page only)
+
+---
+
+## 3. Use Cases
+
+### When to Use This Widget
+
+1. **Simple lists of related pages**
+   - Display child pages of the current page
+   - Show related documents or tasks
+   - List team members or stakeholders
+   - Display items in a specific category
+
+2. **Quick navigation lists**
+   - Create navigation menus based on dynamic queries
+   - Show recently modified pages
+   - Display favorited or tagged items
+   - List pages in a specific workspace
+
+3. **Embedded in rich text content**
+   - Include dynamic lists within documentation
+   - Show related references in description fields
+   - Embed contextual search results in page content
+
+4. **Lightweight result display**
+   - When you only need to show page names/links
+   - When table columns and advanced formatting are unnecessary
+   - For mobile-friendly simple lists
+
+5. **Filtered content views**
+   - Show items matching specific criteria
+   - Display content based on status, category, or type
+   - Filter by custom attributes or relationships
+
+### When NOT to Use This Widget
+
+- **Tabular data display**: Use `cf.platform.embeddedSearchAsTable` instead for column-based views
+- **Large result sets**: Limited to 1000 results; use table widget with pagination for larger datasets
+- **Complex data presentation**: Use table widget when you need to show multiple attributes per result
+- **Interactive filtering**: Use connected table filter widget for user-controlled filtering
+- **Charts and visualizations**: Use chart widgets (pie, bar, etc.) for visual data representation
+
+### Comparison with Similar Widgets
+
+| Widget | Purpose | Output Format | Best For |
+|--------|---------|---------------|----------|
+| `cf.platform.embeddedSearchAsList` | Simple list of search results | Unordered list (ul/li) | Quick navigation, simple lists |
+| `cf.platform.embeddedSearchAsTable` | Tabular search results | HTML table with columns | Data with multiple attributes |
+| `cf.platform.incomingReferences` | Show pages referencing current page | List of links | Relationship visualization |
+| `cf.platform.wiki` | Static rich text content | Formatted text | Non-dynamic content |
+
+---
+
+## 4. Configuration Concepts
+
+### Main Configuration Options
+
+The widget is configured using the `cf.platform.embeddedSearchAsList` type definition with the following attributes:
+
+#### 1. **Search Query** (Required)
+- **Attribute**: `SEARCH`
+- **Type**: `SingleStringAttributeDef` (JSON-serialized search)
+- **Purpose**: Defines what pages/entities to find
+- **Components**:
+  - **Filters**: Type filters, space filters, attribute filters, etc.
+  - **Text search**: Optional full-text search query
+  - **Context**: Can reference embedding entity for dynamic queries
+
+**Example Search Scenarios**:
+```java
+// Find child pages of current page
+Search search = new Search();
+search.add(Filters.type(PlatformAppTypes.DEFAULT_PAGE_TYPE.TYPE));
+search.add(Filters.customAttribute(PlatformAppTypes.DEFAULT_PAGE_TYPE.PARENT, currentPage));
+```
+
+#### 2. **Widget Title** (Optional)
+- **Attribute**: `LOCALIZED_TITLE`
+- **Type**: `SingleLocalizedStringAttributeDef`
+- **Purpose**: Custom title displayed above the list
+- **Default**: If not provided, uses the search query as human-readable text (e.g., "Pages of type 'Task' in space 'Project A'")
+
+#### 3. **Sort Column** (Optional)
+- **Attribute**: `SORT_COLUMN`
+- **Type**: `SingleStringAttributeDef`
+- **Purpose**: Attribute to sort results by (JSON-serialized attribute reference)
+- **Behavior**:
+  - If specified, overrides default sorting
+  - Works together with Sort Order
+  - Applied after search filters
+
+#### 4. **Sort Order** (Optional)
+- **Attribute**: `SORT_ORDER`
+- **Type**: `SingleStringAttributeDef` (enum)
+- **Values**:
+  - `ENUM_VALUE_ASCENDING` (default)
+  - `ENUM_VALUE_DESCENDING`
+- **Purpose**: Controls direction of sorting
+- **Default Behavior**:
+  - If no sort column is specified and no text search is used, automatically sorts alphabetically
+  - Text searches use relevance scoring by default
+
+#### 5. **Height** (Optional)
+- **Attribute**: `HEIGHT`
+- **Type**: `SingleNumberAttributeDef`
+- **Purpose**: Fixed height in pixels for the widget container
+- **Default**: Auto-sized to content
+
+### Search Query Features
+
+The search configuration (stored as JSON) supports:
+
+1. **Type Filters**: Restrict to specific entity types
+2. **Space Filters**: Limit to specific workspaces
+3. **Attribute Filters**: Filter by attribute values
+   - Text attributes
+   - Number attributes
+   - Date attributes
+   - Reference attributes (links to other pages)
+   - Boolean attributes
+   - Enum attributes
+4. **Full-text Search**: Search across all text content
+5. **Complex Filter Logic**: AND, OR, NOT combinations
+6. **Dynamic Context**: Use embedding entity in filter expressions
+
+---
+
+## 5. Technical Details
+
+### Implementation Architecture
+
+**Definition Class**: `EmbeddedSearchAsListWidgetDefinition.java:41-171`
+
+**Template File**: `embeddedSearchAsListWidgetDefinition.htm` (lines 1-15)
+
+**Key Methods**:
+1. `embeddedSearchAsList()` - Creates widget substitution with search execution
+2. `init()` - Parses configuration, executes search, applies sorting
+3. `putSubstitutions()` - Provides template variables for rendering
+4. `getTitle()` - Returns configured title or human-readable search description
+
+### Template Variables
+
+The widget template receives these substitutions:
+
+1. **hits** - `SimpleListSubstitution` of `Linkable` entities
+   - Each hit wraps a search result entity
+   - Provides `.link()` method for rendering
+2. **moreHits** - `ConditionalSubstitution` (boolean)
+   - True when totalHitCount > hitsPerPage (1000)
+3. **currentHits** - Number of results displayed
+4. **totalHits** - Total number of matching results
+
+### Template Rendering
+
+```html
+$[hits$
+$[moreHits$
+<p class="alert alert-info">Only the first {currentHits} of {totalHits} results are shown.</p>
+$moreHits]$
+	<ul>
+		$[hits h$
+			<li>
+				$h.link()$
+			</li>
+		$hits]$
+	</ul>
+$]hits[$
+<p class="alert alert-info">No results</p>
+$hits]$
+```
+
+### Search Execution
+
+**Location**: `EmbeddedSearchAsListWidgetDefinition.java:64-85`
+
+```java
+// Parse search from configuration
+search = Search.getFromJson(
+    configuration.get(EMBEDDED_SEARCH_AS_LIST.SEARCH),
+    PersistentEntity.getPersistentEntityByUidNoReadAccessCheck(params.entityUid)
+);
+
+// Apply custom sorting if configured
+String sort = configuration.get(EMBEDDED_SEARCH_AS_LIST.SORT_COLUMN);
+if (!Strings.isNullOrEmpty(sort)) {
+    String sortOrder = configuration.get(EMBEDDED_SEARCH_AS_LIST.SORT_ORDER);
+    boolean descending = Objects.equals(SEARCH_MIXIN.ENUM_VALUE_DESCENDING, sortOrder);
+    search.addSortFromJson(sort, descending);
+} else if (search.getText() == null) {
+    // Fallback: alphabetical sort when no custom sort and no text search
+    search.addAlphabeticalSortIfNotSorted();
+}
+
+// Execute search (page 1, up to 1000 results)
+searchResult = search.find(1, 1000);
+```
+
+### Result Limiting
+
+- **Hard limit**: 1000 results maximum (single page)
+- **Feedback**: Shows alert when results are truncated
+- **Message**: "Only the first 1000 of X results are shown."
+
+---
+
+## 6. Relationship to Other Widgets
+
+### Related Widgets
+
+1. **cf.platform.embeddedSearchAsTable** (Sibling Widget)
+   - Same search capabilities
+   - Tabular output with configurable columns
+   - Multi-column sorting support
+   - Connected table filtering
+   - Better for complex data display
+
+2. **cf.platform.connectedTableFilter**
+   - Works with embeddedSearchAsTable (not with list)
+   - Provides interactive filtering controls
+   - Updates table results dynamically
+
+3. **cf.platform.incomingReferences**
+   - Shows backlinks to current page
+   - Predefined search (no configuration)
+   - Similar list output format
+
+4. **cf.platform.incomingLinks**
+   - Shows pages linking to current page
+   - Different from references (explicit attribute-based links)
+
+### Widget Family: Search-Based Widgets
+
+The embedded search widgets are part of a family that displays search results:
+
+- **List variant** (this widget): Simple list output
+- **Table variant**: Column-based table output
+- **Chart variants**: Visual representations (pie, bar charts)
+- **Matrix variant**: Two-dimensional grouping
+
+All share the common search configuration pattern but differ in presentation.
+
+---
+
+## 7. Context and Dependencies
+
+### Prerequisites
+
+1. **Search API**: Relies on cplace's search infrastructure
+2. **Entity Type System**: Queries against type definitions
+3. **Elasticsearch**: Indexed search execution
+4. **Linkable Adapter**: Results must be adaptable to `Linkable` interface
+
+### Embedding Contexts
+
+Can be embedded in:
+1. **Pages**: Via widget containers in page layouts
+2. **Type Definitions**: In type-specific layouts
+3. **Alternative Layouts**: Custom layout variants
+4. **Rich String Attributes**: Using widget insertion syntax
+5. **Rich String Widgets**: As nested widgets
+
+### Access Control
+
+- **Search respects permissions**: Only shows entities user can access
+- **No special widget permissions**: Uses standard read access checks
+- **Embedding entity context**: Can filter based on embedding page
+
+---
+
+## 8. Messages and Localization
+
+### Widget Metadata
+
+**English Messages** (`messages_en.properties`):
+- **Name**: "List"
+- **Description**: "Generates a list of search results sorted alphabetically."
+
+### Template Messages
+
+1. **moreResults**: "Only the first {0} of {1} results are shown."
+   - Used when results exceed 1000
+   - `{0}` = currentHits (1000)
+   - `{1}` = totalHits
+
+2. **no_results**: "No results"
+   - Shown when search returns zero results
+
+---
+
+## 9. Icon and Visual Identity
+
+**Icon**: `fa-list-alt` (Font Awesome icon)
+- Represents list/document concept
+- Distinguishes from table widget (fa-table)
+
+---
+
+## 10. Code Examples
+
+### Example 1: Create Widget Programmatically
+
+```java
+// Create a widget to list child pages
+Search search = new Search();
+search.add(Filters.type(PlatformAppTypes.DEFAULT_PAGE_TYPE.TYPE));
+search.add(Filters.customAttribute(PlatformAppTypes.DEFAULT_PAGE_TYPE.PARENT, currentPage));
+
+WidgetConfiguration wc = WidgetConfiguration.SCHEMA.createWithRandomIdForKind(
+    EmbeddedSearchAsListWidgetDefinition.KIND
+);
+wc.set(WidgetTypes.EMBEDDED_SEARCH_AS_LIST.SEARCH, search.serializeAsJson());
+wc.set(WidgetTypes.EMBEDDED_SEARCH_AS_LIST.LOCALIZED_TITLE,
+    Message.dynamicMessage("Child Pages")
+);
+```
+
+### Example 2: Embed in Rich String
+
+```java
+// Create widget configuration
+WidgetConfiguration wc = WidgetConfiguration.SCHEMA.createWithRandomIdForKind(
+    EmbeddedSearchAsListWidgetDefinition.KIND
+);
+wc.set(WidgetTypes.EMBEDDED_SEARCH_AS_LIST.SEARCH, searchJson);
+
+// Embed in rich string attribute
+String richString = "Here are the related items:\n" +
+    RichStringUtilities.embeddedWidgetInsertion(WidgetHelper.escapeEmbeddedWidget(wc));
+
+page.setCustomRichString("description", richString);
+```
+
+### Example 3: Search with Custom Sort
+
+```java
+Search search = new Search();
+search.add(Filters.type(MyTypes.TASK.TYPE));
+search.add(Filters.space(currentSpace));
+
+WidgetConfiguration wc = WidgetConfiguration.SCHEMA.createWithRandomIdForKind(
+    EmbeddedSearchAsListWidgetDefinition.KIND
+);
+wc.set(WidgetTypes.EMBEDDED_SEARCH_AS_LIST.SEARCH, search.serializeAsJson());
+
+// Sort by due date, descending
+wc.set(WidgetTypes.EMBEDDED_SEARCH_AS_LIST.SORT_COLUMN,
+    MyTypes.TASK.DUE_DATE.toJson()
+);
+wc.set(WidgetTypes.EMBEDDED_SEARCH_AS_LIST.SORT_ORDER,
+    WidgetTypes.SEARCH_MIXIN.ENUM_VALUE_DESCENDING
+);
+```
+
+---
+
+## 11. Migration and Compatibility
+
+### Deprecated Configuration
+
+**Old Attribute**: `TITLE` (Single String)
+- **Status**: Deprecated, kept for migration
+- **Replacement**: `LOCALIZED_TITLE` (Localized String)
+- **Migration**: Handled by `migrateWidgetConfiguration()` method
+
+### Backward Compatibility
+
+The widget maintains backward compatibility through:
+1. Automatic migration of old title format
+2. Preserved configuration structure
+3. Graceful handling of missing optional attributes
+
+---
+
+## 12. Limitations
+
+1. **Result Limit**: Maximum 1000 results displayed
+2. **No Pagination**: Single page only (unlike table widget)
+3. **Simple Output**: Only page names/links (no custom formatting)
+4. **No Interactive Filtering**: Static search (unlike connected table filter)
+5. **No Column Configuration**: Fixed list format
+6. **No Grouping**: Flat list structure
+
+---
+
+## 13. Best Practices
+
+1. **Use meaningful titles**: Help users understand the list purpose
+2. **Keep searches focused**: Avoid overly broad queries that hit 1000+ results
+3. **Leverage sorting**: Make lists more useful with appropriate sort orders
+4. **Consider alternatives**: Use table widget for richer data display
+5. **Test permissions**: Verify widget respects access controls
+6. **Use dynamic searches**: Reference embedding entity for context-aware lists
+7. **Provide context**: Embed in rich text with explanatory text
+
+---
+
+## 14. Testing and Validation
+
+### Test Coverage
+
+**Test Class**: `TestImportWithRichStringEmbeddedWidgetWithRef.java:210-313`
+
+**Test Scenarios**:
+1. Widget references in search filters are preserved during export/import
+2. Space filters are updated during space cloning
+3. Search configurations remain valid after entity migration
+
+**Key Test Pattern** (lines 266-276):
+```java
+// Create widget with search for child pages
+Search search = new Search();
+search.add(Filters.space(sourceSpace));
+search.add(Filters.type(PlatformAppTypes.DEFAULT_PAGE_TYPE.TYPE));
+search.add(Filters.customAttribute(PlatformAppTypes.DEFAULT_PAGE_TYPE.PARENT, sourcePage));
+
+WidgetConfiguration wc = WidgetConfiguration.SCHEMA.createWithRandomIdForKind(
+    EmbeddedSearchAsListWidgetDefinition.KIND
+);
+wc.set(WidgetTypes.EMBEDDED_SEARCH_AS_LIST.SEARCH, search.serializeAsJson());
+wc.set(WidgetTypes.EMBEDDED_SEARCH_AS_LIST.LOCALIZED_TITLE, Message.dynamicMessage("Children"));
+```
+
+---
+
+## 15. Summary
+
+The `cf.platform.embeddedSearchAsList` widget is a lightweight, search-driven widget that displays query results as a simple clickable list. It's ideal for navigation lists, related items, and embedded dynamic content where tabular formatting is unnecessary.
+
+**Key Strengths**:
+- Simple configuration and usage
+- Flexible search capabilities
+- Embeddable in multiple contexts
+- Automatic alphabetical sorting fallback
+- Clean, minimal output
+
+**Key Limitations**:
+- 1000 result maximum
+- No pagination
+- Simple list format only
+- No interactive filtering
+
+**When to Choose This Widget**:
+- You need a simple list of links
+- Results are under 1000 items
+- You don't need column-based display
+- You want embedded, dynamic content
+- Mobile-friendly presentation is important