@cplace/mcp-server 1.6.0 → 1.6.1

package/dist/widget-specifications/_research_from_ga_products/cf-cplace-dragAndDropImageView-imageWithTextAndListWidget/research.md

@@ -1,326 +0,0 @@
-# Research: Image with Text and List Widget
-
-**Widget ID:** `cf.cplace.dragAndDropImageView.imageWithTextAndListWidget`
-**Repository:** `cplace-paw`
-**Plugin:** `cf.cplace.dragAndDropImageView`
-
-## Quick Description
-
-The Image with Text and List widget displays a background image with an overlay of styled text and a scrollable list of search results, combining visual presentation with dynamic content from a configurable search query.
-
----
-
-## Purpose and Core Functionality
-
-The `imageWithTextAndListWidget` is an advanced visualization widget that combines three key elements:
-
-1. **Background Image**: A configurable image that serves as the visual foundation
-2. **Text Overlay**: Rich text content positioned at various locations on the image
-3. **Search Results List**: A dynamically generated list of pages based on a configurable search query
-
-This widget extends the simpler `imageWithTextWidget` by adding the search results list component, making it ideal for creating visual dashboards or navigation hubs that combine imagery with actionable, data-driven content.
-
-**Key Implementation Details:**
-- Definition class: `ImageWithTextAndListWidgetDefinition.java` (line 35)
-- Template file: `imageWithTextAndListWidgetDefinition.htm`
-- Frontend controller: `DragAndDropImageWithTextAndListCtrl.ts`
-- Widget type configuration: `IMAGE_WITH_TEXT_AND_LIST_WIDGET.TYPE` (line 224)
-
----
-
-## Use Cases
-
-### 1. Visual Navigation Dashboard
-Create an attractive landing page that combines branding imagery with a list of important pages or documents. The background image provides context while the list offers quick navigation to relevant content.
-
-**Example:** A project overview page with a hero image and a list of active work packages.
-
-### 2. Status Board with Context
-Display a visual representation (e.g., architecture diagram, process map) with an overlay showing related items from a search query.
-
-**Example:** An infrastructure diagram with a list of servers or components matching specific criteria.
-
-### 3. Content Hub
-Combine marketing or informational imagery with dynamically filtered content lists.
-
-**Example:** A product category page showing a product image with a list of related documents, specifications, or support materials.
-
-### 4. Task/Issue Tracker with Visual Context
-Display a background image representing a location, team, or project phase alongside a filtered list of tasks or issues.
-
-**Example:** A construction site photo with a list of open issues for that location.
-
----
-
-## Configuration Concepts
-
-The widget provides comprehensive configuration through the `IMAGE_WITH_TEXT_AND_LIST_WIDGET.TYPE` configuration type (DragAndDropImageViewWidgetTypes.java:202-239):
-
-### Image Configuration
-
-**Reference Attribute** (`ATTRIBUTE_NAME`, line 206)
-- Points to a document reference attribute on the page
-- The referenced document serves as the background image
-- Supports drag-and-drop image upload and selection from available documents
-
-**Scaling** (`SCALING`, line 212)
-- Controls how the image fills the widget area
-- Options:
-  - `horizontal`: Cover with full width, crop height if needed (background-size: cover)
-  - `vertical`: Full height, auto width, centered (background-size: auto 100%)
-  - `fit`: Contain entire image, centered (background-size: contain)
-
-**Fixed Height** (`FIXED_HEIGHT`, line 210)
-- Optional height constraint in pixels
-- Allows precise control over widget dimensions
-
-### Text Overlay Configuration
-
-**Text Content** (`TEXT`, line 214)
-- Rich text field supporting HTML formatting
-- Default example shows styled text with black background and white color
-- Can embed other widgets via `WidgetUtil.insertWidgetsInRichString()` (ImageWithTextAndListWidgetDefinition.java:90)
-
-**Text Position** (`TEXT_POSITION`, line 216)
-- Seven positioning options:
-  - `bottom-left`, `bottom-centered`, `bottom-right`
-  - `top-left`, `top-centered`, `top-right`
-  - `centered` (absolute center)
-- Implemented via CSS absolute positioning (imageWithTextAndList.less:114-162)
-
-### Search and List Configuration
-
-**Search Query** (`SEARCH`, line 218)
-- JSON-based search configuration
-- Executes against pages in the system
-- Maximum 100 results (MAX_RESULTS constant, line 41)
-- Parsed via `Search.getFromJson()` (ImageWithTextAndListWidgetDefinition.java:93)
-
-**Sorting** (lines 220-222)
-- `SORT_COLUMN`: Attribute to sort by
-- `SORT_ORDER`: Ascending or descending
-- Fallback: Alphabetical sort if no text search or custom sort specified (line 102)
-
-**List Display:**
-- Appears as floating scrollable list on the right side of the image
-- Each item renders as a clickable link via `$h.link()$` template substitution
-- Styled with gray background, white text, hover effects (imageWithTextAndList.less:44-110)
-- Uses nanoScroller for smooth scrolling (cfCplaceDragAndDropImageWithTextAndList.ts:11)
-
-### Frame and Title
-
-**Show Frame** (`SHOW_FRAME`, line 208)
-- Boolean toggle for widget frame display
-- Default: true
-
-**Localized Title** (`LOCALIZED_TITLE`, line 204)
-- Multi-language widget title support
-- Inherited from base widget mixin
-
----
-
-## Architecture and Component Relationships
-
-### Widget Hierarchy
-
-The widget is part of a three-tier widget family in the `cf.cplace.dragAndDropImageView` plugin:
-
-1. **DragAndDropImageWidget** (base)
-   - Image display with drag-and-drop upload
-   - Image selection from available documents
-   - Configurable scaling and height
-
-2. **ImageWithTextWidget** (extends base)
-   - Adds rich text overlay
-   - Adds text positioning
-
-3. **ImageWithTextAndListWidget** (extends ImageWithText)
-   - Adds search functionality
-   - Adds scrollable results list
-
-### State Management
-
-**Backend State** (`ImageWithTextAndListWidgetState.java`)
-- Extends `ImageWithTextWidgetState` which extends `WidgetState`
-- Serialized to JSON for frontend consumption (line 115)
-
-**Frontend State** (`IDragAndDropImageWithTextAndListState`)
-- Extends `IDragAndDropImageWithTextState`
-- Properties:
-  - Image management: `insertUrl`, `removeUrl`, `uploadUrl`, `imageSrc`, `availableImages`
-  - Display: `scaling`, `maxHeight`, `textPosition`, `text`
-  - Search: `hits` (search results)
-  - Access control: `insufficientRights`
-
-### Key Components
-
-**Java Backend:**
-- `ImageWithTextAndListWidgetDefinition.java`: Main widget definition and content rendering
-- `DragAndDropImageViewWidgetTypes.java`: Type system and configuration schema
-- `ImageWithTextAndListWidgetState.java`: State serialization
-
-**TypeScript Frontend:**
-- `DragAndDropImageWithTextAndListCtrl.ts`: Controller extending base image controller
-- `cfCplaceDragAndDropImageWithTextAndList.ts`: Angular directive for initialization
-- `models.ts`: TypeScript interfaces for type safety
-
-**Templates:**
-- `imageWithTextAndListWidgetDefinition.htm`: Handlebars/Velocity template with Angular bindings
-- `imageWithTextAndList.less`: CSS styling for layout and positioning
-
----
-
-## Technical Implementation Details
-
-### Image Management
-
-The widget inherits full drag-and-drop image functionality:
-
-1. **Upload**: Users can upload new images via file input (imageWithTextAndListWidgetDefinition.htm:31-46)
-2. **Select**: Choose from existing document attachments on the page (lines 49-74)
-3. **Insert**: Link selected document to the reference attribute via `InsertHandler`
-4. **Remove**: Clear the reference via `RemoveHandler`
-
-**Access Control:**
-- Read access checked via `Schema.checkReadAccess()` (WidgetState.java:59)
-- Displays "insufficient rights" message if access denied (imageWithTextAndListWidgetDefinition.htm:25-28)
-
-### Search Execution
-
-Search query execution flow (ImageWithTextAndListWidgetDefinition.java:92-108):
-
-1. Parse search JSON from configuration
-2. Apply custom sorting if configured
-3. Fall back to alphabetical sort for non-text searches
-4. Execute `search.findPages(1, MAX_RESULTS)`
-5. Pass results to template as `hits` substitution
-
-The search is entity-aware, executing in the context of the embedded page for proper security and reference resolution.
-
-### Template Rendering
-
-The widget uses a hybrid template approach:
-- Velocity/Handlebars on backend for initial HTML
-- AngularJS directives and bindings for interactivity
-- CSS classes for responsive layout
-
-Key template substitutions (ImageWithTextAndListWidgetDefinition.java:112-119):
-- `state`: Serialized widget state as JSON (HTML attribute escaped)
-- `text`: Rich text content (no escaping, allows HTML)
-- `hits`: List substitution for search results
-
-### Styling Architecture
-
-The LESS stylesheet defines:
-- Responsive image scaling based on `scaling` class
-- Absolute positioning system for text overlays
-- Floating scrollable list container (300px fixed width)
-- Interactive list item styles with hover effects
-- Progress bar for upload feedback
-
-### Prerequisites and Dependencies
-
-**Entity Requirements:**
-- Widget must be embedded in a `Page` entity (enforced at line 77)
-- Page must have a document reference attribute configured in `ATTRIBUTE_NAME`
-
-**Plugin Dependencies:**
-- `cf.cplace.platform`: Core platform functionality
-- Base widget system and templating engine
-- Search infrastructure
-- Document/file management
-
-**Frontend Dependencies:**
-- AngularJS
-- jQuery (for nanoScroller)
-- Bootstrap (for button and table styles)
-
----
-
-## Related Widgets and Context
-
-### Widget Family
-
-The `cf.cplace.dragAndDropImageView` plugin provides three related widgets:
-
-1. **cf.cplace.dragAndDropImageView.dragAndDropImageViewWidget**
-   - Basic image display with upload/selection
-   - Use when only image is needed
-
-2. **cf.cplace.dragAndDropImageView.imageWithTextWidget**
-   - Image + text overlay
-   - Use for annotated images without search results
-
-3. **cf.cplace.dragAndDropImageView.imageWithTextAndListWidget** (this widget)
-   - Image + text + search results list
-   - Use for visual dashboards with dynamic content
-
-### When to Use This Widget vs. Alternatives
-
-**Choose Image with Text and List Widget when:**
-- You need visual context (image) combined with actionable links (search results)
-- Content should update dynamically based on search criteria
-- You want a dashboard-style visual navigation experience
-
-**Choose simpler alternatives when:**
-- No search results needed → Use `imageWithTextWidget`
-- No text overlay needed → Use `dragAndDropImageViewWidget`
-- No image needed → Use standard search/list widgets
-
----
-
-## Configuration Flow
-
-### Setup Process
-
-1. **Add Widget to Page**
-   - Place widget on a page layout
-   - Widget embeds in any page type
-
-2. **Configure Reference Attribute**
-   - Select which document reference attribute holds the image
-   - Attribute must exist on the page's type definition
-
-3. **Upload/Select Image**
-   - Drag-and-drop image file, or
-   - Select from existing page attachments
-
-4. **Configure Text Overlay (Optional)**
-   - Enter rich text content with HTML styling
-   - Choose positioning (top/bottom/center, left/center/right)
-
-5. **Configure Search**
-   - Define search criteria (JSON-based)
-   - Set sorting column and order
-   - Search returns up to 100 page results
-
-6. **Set Display Options**
-   - Choose image scaling mode (horizontal/vertical/fit)
-   - Set fixed height if needed
-   - Toggle frame visibility
-   - Set localized title
-
-### Runtime Behavior
-
-**On Page Load:**
-1. Widget state initialized from configuration
-2. Image loaded from referenced document
-3. Search query executed in context of embedded page
-4. Results rendered as scrollable list
-5. Text overlay positioned based on configuration
-
-**User Interactions:**
-- Click list items to navigate to linked pages
-- Upload new images (if permitted)
-- Select different images from available documents
-- Remove current image
-
----
-
-## Summary
-
-The Image with Text and List Widget is a sophisticated visualization component that merges static imagery with dynamic, search-driven content. It's particularly valuable for creating visually engaging navigation hubs, status boards, and content portals where context (image) and action (links) should coexist.
-
-The widget's flexibility in image scaling, text positioning, and search configuration makes it adaptable to various use cases while maintaining a clean, professional appearance through carefully designed CSS and responsive layout.
-
-As the most feature-rich widget in the drag-and-drop image family, it offers maximum functionality for users who need the full combination of visual presentation and data-driven lists.