@cplace/test-mcp-server 0.1.15 → 1.1.0

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

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