npm - @cplace/mcp-server - Versions diffs - 1.5.3 → 1.6.1 - Mend

@cplace/mcp-server 1.5.3 → 1.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (797) hide show

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

@@ -1,485 +0,0 @@
-# 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