@cplace/test-mcp-server 0.1.15 → 1.1.0

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-genericInterface-api-widgets-triggerInterfaceButton/research.md

@@ -0,0 +1,180 @@
+# Widget Research: Trigger Interface Button
+
+**Widget ID:** `cf.cplace.genericInterface.api.widgets.triggerInterfaceButton`
+**Repository:** `cplace-generic-interface`
+**Definition Class:** `TriggerInterfaceButtonWidgetDefinition.java`
+
+## Overview
+
+The Trigger Interface Button widget provides a clickable button that executes a configured Generic Interface (import/export) on demand. It allows users to manually trigger data integration processes, optionally accepting a file upload as input.
+
+## Purpose
+
+This widget enables users to manually initiate interface operations that are defined in Generic Interface Definition pages. Instead of running interfaces on a schedule or automatically, users can trigger them on-demand through a simple button click within pages or rich text content.
+
+## Core Functionality
+
+The widget:
+1. Displays a customizable button in the UI
+2. When clicked, executes a configured Generic Interface Definition
+3. Optionally accepts file uploads (for import interfaces)
+4. Runs the interface execution as a background job
+5. Displays progress and results to the user
+
+## Use Cases
+
+### 1. Manual Data Import
+- **Scenario:** Users need to import data from external systems on an ad-hoc basis
+- **Example:** Import product catalog updates from a supplier CSV file when needed
+- **Configuration:** Enable file upload option, link to an import interface definition
+
+### 2. On-Demand Data Export
+- **Scenario:** Users want to export current data to external formats when required
+- **Example:** Export project status reports to Excel for stakeholder meetings
+- **Configuration:** Link to an export interface definition, optionally export only the embedding page
+
+### 3. Manual Synchronization
+- **Scenario:** Trigger synchronization with external systems without waiting for scheduled runs
+- **Example:** Sync issue tracking data with an external bug tracker after making critical updates
+- **Configuration:** Link to a bidirectional interface definition
+
+### 4. Single Page Export
+- **Scenario:** Export just the current page instead of a full dataset
+- **Example:** Export a single project page's data for archival or sharing
+- **Configuration:** Enable "Export Embedding Page" option to export only the page containing the widget
+
+## Configuration Options
+
+The widget extends the Simple Button Widget base class and provides the following configuration options:
+
+### Display Configuration
+- **Caption:** Custom button text (defaults to widget name + interface definition name)
+- **Icon:** Font Awesome icon for the button
+- **Show Frame:** Whether to display a border around the widget
+- **Alignment:** Horizontal alignment (left, center, right)
+
+### Interface Configuration
+- **Interface Definition:** Reference to the Generic Interface Definition page to execute
+  - If not specified, the embedding page itself must be an Interface Definition
+- **Upload File:** Boolean flag to enable file upload dialog before execution
+  - When enabled, displays a file upload form
+  - Uploaded file is stored temporarily and passed to the interface
+- **Same Workspace:** Controls workspace context for the interface execution (default: true)
+- **Export Embedding Page:** When enabled, exports only the page where the widget is embedded
+  - Useful for single-page exports
+  - Automatically builds a search filter for just that page
+
+## Technical Details
+
+### Class Hierarchy
+```
+WidgetDefinition
+  └── SimpleButtonWidgetDefinition
+        └── TriggerInterfaceButtonWidgetDefinition
+```
+
+### Handler Flow
+1. **TriggerInterfaceFileUploadEditHandler:**
+   - Validates configuration
+   - If file upload is enabled, displays upload form
+   - Otherwise forwards directly to submit handler
+
+2. **TriggerInterfaceSubmitHandler:**
+   - Processes uploaded file (if any) - stores in tenant's import directory
+   - Builds and triggers the interface job via `TriggerInterfaceUtilities`
+   - Creates a job progress dialog or displays results
+
+### Integration Points
+- **Generic Interface Definitions:** The widget requires a valid Interface Definition page that specifies:
+  - Runner type (import/export)
+  - Processor type (CSV, Excel, XML, JSON, JDBC, etc.)
+  - Mapping configuration
+  - Communication settings (optional)
+
+- **Job System:** Interface execution runs as a `PersistentJob`, allowing:
+  - Background processing
+  - Progress tracking
+  - Error logging
+
+## Relationship to Other Components
+
+### Generic Interface System
+The widget is part of the broader Generic Interface framework that includes:
+- **Interface Definitions:** Configuration pages that define import/export operations
+- **Runners:** Execute the actual interface logic (file-based, JDBC, REST, etc.)
+- **Processors:** Handle specific file formats (CSV, Excel, XML, JSON, etc.)
+- **Mappers:** Define how data maps between cplace and external systems
+- **Error Logging:** Track interface execution issues
+
+### Related Widgets
+- Part of the Simple Button Widget family
+- Can be embedded in rich text or as standalone widgets
+
+## Embedding Requirements
+
+- Can be embedded as a widget (`WidgetEmbedding.AS_WIDGET`)
+- Can be embedded in rich strings (`WidgetEmbedding.INSIDE_RICHSTRING`)
+- Cannot be embedded in other contexts (e.g., not in tables)
+- Subject to app space embedding restrictions
+
+## Validation
+
+The widget performs several validations:
+1. **Interface Definition Required:** Either an interface must be configured in the widget, or the embedding page must be an Interface Definition
+2. **Export Embedding Page:** When enabled, an interface definition must be explicitly configured
+3. **Access Permissions:** Standard action permissions apply based on the handler class
+
+## Example Scenarios
+
+### Scenario 1: CSV Import Button
+```
+Configuration:
+- Caption: "Import Customer Data"
+- Icon: "fa-upload"
+- Upload File: true
+- Interface Definition: → Customer CSV Import Interface
+- Same Workspace: true
+
+User Experience:
+1. User clicks "Import Customer Data" button
+2. File upload dialog appears
+3. User selects CSV file
+4. Interface processes file in background
+5. Progress dialog shows import status
+6. Results displayed with error/warning counts
+```
+
+### Scenario 2: Single Page Export Button
+```
+Configuration:
+- Caption: "Export This Project"
+- Icon: "fa-download"
+- Export Embedding Page: true
+- Interface Definition: → Project Excel Export Interface
+- Same Workspace: true
+
+User Experience:
+1. User views a specific project page
+2. Clicks "Export This Project" button
+3. Interface executes immediately (no file upload needed)
+4. Excel file generated with just this project's data
+5. Download link provided or file sent to configured destination
+```
+
+### Scenario 3: Interface Definition Page
+```
+Configuration:
+- Caption: "Run This Interface"
+- Interface Definition: (empty - uses embedding page)
+- Upload File: false
+
+User Experience:
+1. User navigates to an Interface Definition page
+2. Widget button is embedded in the page
+3. Clicking button executes the interface with its configured settings
+4. Useful for testing or manual execution of scheduled interfaces
+```
+
+## Summary
+
+The Trigger Interface Button widget bridges the gap between automated data integration and user-initiated operations. It provides a simple, intuitive way to execute complex import/export processes with optional file handling, progress tracking, and error management. This makes it valuable for scenarios where timing, data availability, or business logic requires human judgment before triggering data integration operations.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-landingPageFromPage-quickOverview/research.md

@@ -0,0 +1,186 @@
+# Widget Research: Quick Overview
+
+**Widget ID:** `cf.cplace.landingPageFromPage.quickOverview`
+**Repository:** `cplace-paw`
+**Plugin:** `cf.cplace.landingPageFromPage`
+
+---
+
+## 1. Purpose Summary
+
+**Short Description (1-2 sentences):**
+The Quick Overview widget displays a compact summary of search results at a glance, showing a configurable count of items with a total hit count, title, subtitle, and optional "create new" button. It is designed for landing pages where users need a fast visual summary of key content categories.
+
+---
+
+## 2. Core Functionality
+
+### What the Widget Does
+
+The Quick Overview widget executes a saved search and presents the results in a dashboard-style tile format:
+
+1. **Header Section**: Displays a configurable title, subtitle, and icon
+2. **Statistics Area**: Shows the total hit count alongside the type name (singular/plural based on count)
+3. **Item List**: Renders a limited number of search results as clickable links with icons
+4. **Create Button**: Optionally shows a "+" button to create new items matching the search criteria
+
+### Key Implementation Details
+
+From `QuickOverviewWidgetSubstitution.java`:
+- Executes a search defined in the widget configuration
+- Sorts results alphabetically (ascending or descending based on configuration)
+- Limits displayed results to the configured "hits" count
+- Each item shows: name, icon, and links to the page URL
+- Supports multi-workspace searches (removes space filter if multiple workspaces selected)
+
+---
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Landing Page Dashboard Tiles**
+   Display quick summaries of different content types on a landing page. For example:
+   - "5 Active Projects" showing the first 3 project names
+   - "12 Open Tasks" showing the first 5 task names
+   - "8 Team Members" showing a few team member names
+
+2. **Content Category Overview**
+   Provide users with at-a-glance counts and quick access to filtered content categories without navigating to full search results.
+
+3. **Quick Navigation Hubs**
+   Create clickable entry points to frequently accessed content types, combining a summary count with direct links to specific items.
+
+### When to Choose This Widget
+
+- **Choose Quick Overview when:** You need a compact summary tile showing count + limited items
+- **Choose Simple List Overview instead when:** You need a scrollable list with subtitles, custom item icons based on attributes, or link to an overview page
+
+### Problems It Solves
+
+- Reduces navigation steps by surfacing key content directly on landing pages
+- Provides visual summary of content distribution across categories
+- Enables quick item creation without leaving the landing page context
+
+---
+
+## 4. Configuration Options
+
+### Configuration Type
+`cf.cplace.landingPageFromPage.quickOverviewConfig`
+
+### Available Configuration Attributes
+
+| Attribute | Type | Description |
+|-----------|------|-------------|
+| `TITLE` | LocalizedString | Main title displayed at the top of the widget |
+| `SUBTITLE` | LocalizedString | Secondary text shown below the title |
+| `ICON` | String (icon) | Icon class displayed next to the title (FontAwesome) |
+| `SEARCH` | String (JSON) | The search configuration defining what content to display |
+| `SORT_COLUMN` | String | Column used for sorting results |
+| `SORT_ORDER` | String | Sort direction (ascending/descending) - defaults to alphabetical |
+| `SHOW_BUTTON` | Boolean | Whether to show the "create new" button (defaults to `true`) |
+| `HITS` | Number | Number of items to display in the list (precision: 0, whole numbers) |
+
+### Configuration Notes
+
+- The search must target a single workspace and single type for the create button functionality to work properly
+- If multiple workspaces are selected, the space filter is removed from the search
+- Alphabetical sorting is applied regardless of the sort column setting (either ascending or descending)
+
+---
+
+## 5. Context and Relationships
+
+### Part of the Landing Page from Page Plugin
+
+This widget belongs to the **Landing Page from Page** app (`cf.cplace.landingPageFromPage`), which enables creating landing pages within any workspace that are displayed without workspace navigation.
+
+### Related Widgets in the Same Plugin
+
+| Widget | ID | Differentiation |
+|--------|-------|-----------------|
+| **Simple List Overview** | `cf.cplace.landingPageFromPage.simpleListWithAttachment` | Shows all search results with subtitles (via pattern), configurable height, folder link, and per-item icon based on enum attribute |
+| **Welcome Message** | (session user name widget) | Displays username with customizable greeting message |
+
+### Key Differences: Quick Overview vs Simple List Overview
+
+| Feature | Quick Overview | Simple List Overview |
+|---------|----------------|---------------------|
+| Hit count display | Yes (prominent) | No |
+| Subtitle per item | No | Yes (via pattern) |
+| Configurable height | No | Yes |
+| Link to overview page | No | Yes |
+| Icon source | Page's default icon | Configurable from enum attribute |
+| Display mode | Summary tile | Scrollable list |
+
+### Dependencies
+
+- **Platform dependency:** `cf.cplace.platform`
+- Uses platform search functionality for content retrieval
+- Uses platform icon service for icon rendering
+- Relies on platform widget framework for rendering
+
+---
+
+## 6. Visual Structure
+
+Based on the HTML template (`quickOverviewWidgetDefinition.htm`):
+
+```
+┌─────────────────────────────────────┐
+│ [icon] Title                    [+] │  <- Header with optional create button
+│ Subtitle                            │
+├─────────────────────────────────────┤
+│ Projects              │             │  <- Type name + hit count
+│ 12                    │             │
+├─────────────────────────────────────┤
+│ • [icon] Project Alpha              │  <- Clickable item list
+│ • [icon] Project Beta               │
+│ • [icon] Project Gamma              │
+└─────────────────────────────────────┘
+```
+
+### CSS Classes (for styling reference)
+
+- `.cf-cplace-landing-page-from-page-qo-wrapper` - Main container
+- `.qo-head` - Header section
+- `.qo-title` - Title text
+- `.qo-subtitle` - Subtitle text
+- `.qo-icon` - Icon elements
+- `.qo-add-new` - Create button container
+- `.qo-items` - Statistics area
+- `.qo-item-typename` - Type name display
+- `.qo-item-hit-count` - Hit count number
+- `.qo-list` - List container
+- `.qo-list-items` - List ul element
+- `.qo-list-item` - Individual list item
+
+---
+
+## 7. Technical Notes
+
+### Widget Icon
+- FontAwesome: `fa-binoculars`
+
+### Rendering Characteristics
+- `isNoPadding()`: `true` - Widget renders without standard padding
+- `showFrame()`: `false` - Widget renders without the standard frame
+
+### Attribute Migration Support
+The widget includes migration support for:
+- Search attribute updates
+- Sort column attribute name changes (handles `SORT_PREFIX_FIELD` prefixed columns)
+
+---
+
+## 8. Source Files Reference
+
+| File | Purpose |
+|------|---------|
+| `QuickOverviewWidgetDefinition.java` | Widget definition, configuration type, icon |
+| `QuickOverviewWidgetSubstitution.java` | Template rendering logic, search execution |
+| `LandingPageWidgetTypes.java` | Configuration attribute definitions |
+| `quickOverviewWidgetDefinition.htm` | HTML template |
+| `messages_en.properties` | Localized strings |
+| `LandingPageFromPagePlugin.java` | Plugin registration |

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-landingPageFromPage-sessionUserNameWidget/research.md

@@ -0,0 +1,158 @@
+# Widget Research: Welcome Message with User Name Widget
+
+**Widget ID:** `cf.cplace.landingPageFromPage.sessionUserNameWidget`
+**Repository:** `cplace-paw`
+**Plugin:** `cf.cplace.landingPageFromPage`
+**Definition Class:** `WelcomeMessageWithUserNameWidgetDefinition.java`
+
+---
+
+## 1. Purpose and Core Functionality
+
+### Summary
+The Welcome Message widget displays a personalized greeting to the currently logged-in user, combining their name with configurable welcome messages from the app configuration.
+
+### How It Works
+
+1. **User Name Resolution**: The widget retrieves the current session user via `SessionLocal.getUser()` and extracts their display name.
+
+2. **Message Selection**: The widget retrieves a list of configurable localized welcome messages from the app configuration (`APP_CONFIGURATION.MESSAGES`). If messages are configured, one is randomly selected for display.
+
+3. **Placeholder Substitution**: The selected message can contain a `<name>` placeholder which is replaced with the current user's name. For example, a configured message like "Welcome back, <name>!" would render as "Welcome back, John Doe!".
+
+4. **Fallback Behavior**: If no custom messages are configured, the widget simply displays the user's name.
+
+5. **Localization**: Messages are localized strings, meaning they automatically display in the user's preferred language.
+
+### Display Characteristics
+- **No Frame**: The widget renders without a frame/border (`showFrame()` returns `false`)
+- **No Padding**: The widget has no internal padding (`isNoPadding()` returns `true`)
+- **Minimal Template**: Uses a simple wrapper div with class `cf-cplace-landing-page-from-page-session-user-name-wrapper`
+
+---
+
+## 2. Use Cases
+
+### Primary Use Case: Landing Page Personalization
+The widget is designed for landing pages to create a welcoming, personalized experience when users access the platform.
+
+**When to Use:**
+- Creating a personal welcome experience on a landing page or dashboard
+- Greeting users by name upon login to their workspace
+- Adding a human touch to an otherwise static landing page
+
+### Specific Scenarios
+
+1. **Corporate Intranet Landing Page**
+   - Display "Good morning, <name>!" or "Welcome to the Team Portal, <name>!"
+   - Makes users feel acknowledged when they access the company workspace
+
+2. **Project Dashboard Entry Point**
+   - "Welcome back, <name>! Here's your project overview."
+   - Provides orientation for users returning to a project workspace
+
+3. **Multi-Language Environment**
+   - Configure different greetings in multiple languages
+   - German: "Willkommen zurück, <name>!"
+   - English: "Welcome back, <name>!"
+   - The widget automatically shows the greeting in the user's preferred language
+
+4. **Randomized Greetings**
+   - Configure multiple messages for variety
+   - "Hello, <name>!" / "Great to see you, <name>!" / "Welcome, <name>!"
+   - One message is randomly selected each time the page loads, adding freshness
+
+---
+
+## 3. Configuration Concepts
+
+### App-Level Configuration
+
+The welcome messages are configured at the **app level** (per workspace), not per widget instance. This means:
+- All instances of this widget in a workspace share the same message pool
+- Configuration is done through the Landing Page from Page app settings
+
+### Configuration Options
+
+| Configuration | Description |
+|--------------|-------------|
+| **Welcome Messages** (`MESSAGES`) | A list of localized strings that serve as greeting templates. Use `<name>` as a placeholder for the user's name. |
+| **Key Visual** (`KEYVISUAL`) | A document reference for a background image (shared with landing page handler, not specific to this widget) |
+
+### Message Placeholder
+- **`<name>`**: The only supported placeholder - gets replaced with the current user's display name
+- Example: `"Hello, <name>! Ready to get started?"` → `"Hello, John Doe! Ready to get started?"`
+
+### Behavioral Notes
+- If multiple messages are configured, one is **randomly selected** on each page load
+- If no messages are configured, only the user's name is displayed (no greeting text)
+- Messages are **localized**, so you can provide different greetings per language
+
+---
+
+## 4. Context and Relationships
+
+### Part of Landing Page from Page App
+This widget is part of the broader "Landing Page from Page" app (`cf.cplace.landingPageFromPage`), which provides functionality for creating landing pages within cplace workspaces.
+
+### Related Widgets in the Same Plugin
+
+| Widget | Purpose |
+|--------|---------|
+| **Quick Overview** (`QuickOverviewWidgetDefinition`) | Shows at-a-glance search results with hit counts |
+| **Simple List Overview** (`SimpleListWithNewAttachmentWidgetDefinition`) | Displays search results as a list with icons and create-new functionality |
+| **Welcome Message** (this widget) | Displays personalized greeting with user name |
+
+### Architectural Context
+
+1. **Landing Page Type**: The plugin defines a `LANDINGPAGE` type that can be used to create landing page content
+2. **Theme Support**: Landing pages support themes (e.g., "Blank") that affect overall styling
+3. **Full Page Handler**: The `LandingPageFromPageHandler` renders landing pages without the typical workspace navigation
+
+### Prerequisites
+- The "Landing Page from Page" app must be enabled in the workspace
+- Welcome messages should be configured in the app settings for meaningful output
+- The user must be logged in (anonymous users would have no name to display)
+
+### Dependencies
+- Depends on `SessionLocal` for current user information
+- Uses the app configuration system to retrieve messages
+- Part of the `cf.cplace.landingPageFromPage` plugin
+
+---
+
+## 5. Technical Reference
+
+### Key Source Files
+
+| File | Purpose |
+|------|---------|
+| `WelcomeMessageWithUserNameWidgetDefinition.java` | Widget definition and content substitution logic |
+| `welcomeMessageWithUserNameWidgetDefinition.htm` | HTML template |
+| `LandingPageFromPageApp.java` | App configuration including message attribute definition |
+| `messages_en.properties` / `messages_de.properties` | Localized widget name and description |
+
+### Widget Template
+```html
+<div class="cf-cplace-landing-page-from-page-session-user-name-wrapper">
+    <span>$welcomeMessage$</span>
+</div>
+```
+
+### Internationalized Strings
+- **Widget Name (EN):** "Welcome Message"
+- **Widget Name (DE):** "Begrüßungstext"
+- **Widget Description (EN):** "Displays the username and a customizable greeting message"
+- **Widget Description (DE):** "Zeigt den Nutzernamen und eine anpassbare Grußbotschaft an"
+- **Configuration Help (EN):** "Use <name> as a placeholder for the user name"
+- **Configuration Help (DE):** "Verwenden Sie <name> als Platzhalter für den Benutzernamen"
+
+---
+
+## 6. Summary for Documentation
+
+### One-Line Description
+Displays a personalized welcome message with the current user's name, randomly selected from configurable localized greetings.
+
+### Extended Description (1-2 sentences)
+The Welcome Message widget greets logged-in users by name using customizable, localized message templates configured at the app level. Messages can include a `<name>` placeholder that is replaced with the user's display name, and when multiple messages are configured, one is randomly selected for each page load to provide variety.

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-landingPageFromPage-simpleListWithAttachment/research.md

@@ -0,0 +1,135 @@
+# Widget Research: Simple List Overview
+
+**Widget ID:** `cf.cplace.landingPageFromPage.simpleListWithAttachment`
+**Plugin:** `cf.cplace.landingPageFromPage`
+**Repository:** `cplace-paw`
+
+## 1. Purpose & Description
+
+### Short Description
+The Simple List Overview widget displays a scrollable list of pages from a configured search, with optional icons and subtitles, and includes a button to create new items directly from the widget.
+
+### Detailed Description
+This widget is designed for landing pages where users need quick access to a curated list of items (pages) based on a search query. Each list item displays the page name, an optional subtitle (using attribute patterns), and an optional icon derived from an enumeration attribute. The widget supports creating new items of the searched type directly via an "Add New" button that opens a modal dialog.
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+1. **Landing Page Quick Access Lists**
+   - Display a curated list of frequently accessed items (e.g., recent documents, active projects, tasks) on a landing page dashboard
+   - Users can quickly scan and navigate to relevant items
+
+2. **Category-Specific Item Lists**
+   - Show items of a specific type filtered by search criteria (e.g., "My Open Tasks", "Active Projects", "Pending Approvals")
+   - Each list can be configured to show only relevant items for a specific context
+
+3. **Item Creation Entry Point**
+   - Provide users a convenient way to create new items directly from the list
+   - The "New [ItemType]" button streamlines workflows by reducing navigation steps
+
+4. **Visual Item Categorization**
+   - Use enumeration-based icons to visually distinguish item types or statuses at a glance
+   - Subtitles can display additional context like dates, owners, or status information
+
+### When to Use This Widget
+
+- When you need a simple, scrollable list of items on a landing page
+- When users should be able to create new items directly from the list
+- When items need visual differentiation through icons or status indicators
+- When subtitle information helps users identify items quickly
+
+### When NOT to Use This Widget
+
+- When you need advanced table features (sorting, filtering, grouping)
+- When you need to display many attributes per item (use a table widget instead)
+- When you need hierarchical/tree views
+- When items don't have a natural list representation
+
+## 3. Configuration Concepts
+
+### Main Configuration Options
+
+| Configuration | Purpose | Notes |
+|--------------|---------|-------|
+| **Title** | Widget header text | Localized string displayed at the top |
+| **Title Icon** | Icon next to the title | FontAwesome icon name |
+| **Search** | Query to find pages | Defines which pages appear in the list |
+| **Sort Order** | Ascending/Descending | Alphabetical sorting of results |
+| **Hits** | Number of items shown | Limits the displayed results |
+| **Show Create Button** | Enable/disable "New" button | Controls whether users can create items |
+| **Link to Overview Page** | Folder icon destination | Links to a full overview/search page |
+| **Pattern for Subtitles** | Subtitle text pattern | Uses `<attributeName>` syntax for dynamic values |
+| **Icon Enumeration Attribute** | Icon source attribute | Displays enum icons next to each item |
+| **Height** | Widget height | Fixed height for the widget container |
+
+### Subtitle Pattern
+
+The subtitle pattern allows dynamic text composition using attribute values:
+- Syntax: `<attributeName>` inserts the attribute value
+- Example: `Meeting on <cf.cplace.date> about <subject>`
+- Plain text can be mixed with attribute placeholders
+
+### Icon from Enumeration
+
+The widget can display icons from an enumeration attribute:
+- Select an enumeration attribute from the searched type
+- Each list item displays the icon associated with its enum value
+- Provides visual categorization without additional text
+
+## 4. Context & Relationships
+
+### Part of Landing Page from Page App
+
+This widget is one of three widgets provided by the "Landing Page from Page" plugin:
+
+| Widget | Purpose |
+|--------|---------|
+| **Welcome Message** | Displays personalized greeting with username |
+| **Quick Overview** | Shows aggregate counts and recent items for a type |
+| **Simple List Overview** (this widget) | Displays scrollable list with creation capability |
+
+### Related Widgets
+
+- **Quick Overview Widget** (`cf.cplace.landingPageFromPage.quickOverview`): Similar purpose but shows aggregate statistics and hit counts rather than a scrollable list
+- Both share the `CONFIGRATION_MIXIN` base configuration (title, search, hits, icon, show button)
+
+### Plugin Context
+
+The Landing Page from Page plugin enables creating custom landing pages within workspaces:
+- Pages can be configured as landing pages and displayed without workspace navigation
+- The plugin provides specialized widgets designed for dashboard-style layouts
+- App configuration supports key visuals and welcome messages
+
+### Technical Details
+
+- **Template:** `simpleListWithNewAttachmentWidgetDefinition.htm`
+- **Configuration Type:** `cf.cplace.landingPageFromPage.simpleListConfig`
+- **Substitution Class:** `SimpleListWidgetSubstitution`
+- **Icon:** `fa-list-alt`
+
+### Dependencies/Prerequisites
+
+- Search must be configured to return pages (not documents)
+- Search should typically be limited to a single space and type (multi-space searches disable the create button functionality)
+- For icon display, the searched type must have an enumeration attribute with associated icons
+
+## 5. Visual Appearance
+
+The widget has a distinct visual structure:
+- **Header**: Gray background with title, icon, and optional folder link
+- **List Area**: Scrollable container with alternating item styling
+- **List Items**: Name (bold), subtitle below, optional enum icon on left, dropdown menu on hover
+- **Footer**: "New [ItemType]" button with plus icon (when enabled)
+- **Interactions**: Items are clickable links; hover reveals dropdown with "Open in new tab" option
+
+## 6. Source Files Reference
+
+| File | Purpose |
+|------|---------|
+| `SimpleListWithNewAttachmentWidgetDefinition.java` | Widget registration and configuration |
+| `SimpleListWidgetSubstitution.java` | Data preparation and template substitution |
+| `LandingPageWidgetTypes.java` | Configuration type definitions |
+| `simpleListWithNewAttachmentWidgetDefinition.htm` | HTML template |
+| `plugin.css` | Widget styling |
+| `messages_en.properties` | English localization strings |