@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,281 @@
+# Widget Research: cf.cplace.dragAndDropImageView.widget
+
+## Widget Identity
+
+- **Widget ID**: `cf.cplace.dragAndDropImageView.widget`
+- **Display Name**: Image
+- **Repository**: cplace-paw
+- **Plugin**: cf.cplace.dragAndDropImageView
+- **Definition Class**: `DragAndDropImageViewWidgetDefinition.java`
+
+## 1. Purpose
+
+The Drag and Drop Image View widget displays an image from a file reference attribute on a Page and provides intuitive drag-and-drop functionality for image upload and management.
+
+### Short Description
+
+Displays an image from a file reference attribute and allows easy drag-and-drop upload.
+
+## 2. Core Functionality
+
+### What It Does
+
+The widget provides a complete image management solution for cplace Pages:
+
+1. **Image Display**: Shows the image referenced by a specified Page attribute
+2. **Upload Interface**: Provides drag-and-drop file upload capability with a file picker button
+3. **Image Selection**: Displays a table of available images on the Page for quick selection
+4. **Image Removal**: Allows users to remove the current image reference
+5. **Scaling Options**: Supports multiple image scaling modes (horizontal, vertical, fit)
+6. **Lightbox Integration**: Opens images in a lightbox view when clicked
+
+### Technical Implementation
+
+The widget operates by:
+
+- **Reference Management**: Updates a Page's custom reference attribute (pointing to a Document entity)
+- **Image Source**: Retrieves images from Documents that are children of the Page
+- **Upload Flow**: Creates new Document entities as children of the Page when files are uploaded
+- **Backend Handlers**: Uses three dedicated handlers:
+  - `UploadHandler`: Creates new Document from uploaded file
+  - `InsertHandler`: Links existing Document to the attribute
+  - `RemoveHandler`: Clears the attribute reference
+
+## 3. Use Cases
+
+### Primary Use Cases
+
+1. **Hero Images**: Add a prominent image to a Page (e.g., project banner, product photo)
+2. **Visual Context**: Provide visual representation for abstract content (e.g., process diagrams, flowcharts)
+3. **Document Visualization**: Display document previews or scanned images
+4. **Profile Pictures**: Show images associated with person or organization Pages
+5. **Asset Management**: Quick access to upload and select from Page-attached images
+
+### When to Use This Widget
+
+- You need to display a **single image** on a Page
+- The image should be **stored as a Page attribute** (not just a child Document)
+- Users need **easy upload** via drag-and-drop
+- Users should be able to **choose from existing images** on the Page
+- You want **flexible image scaling** options
+
+### When NOT to Use This Widget
+
+- Displaying multiple images (consider image gallery widgets instead)
+- Read-only image display without upload capability (consider simpler image display widgets)
+- Images not stored as Page attributes (consider document list widgets)
+
+## 4. Configuration Concepts
+
+### Required Configuration
+
+**Reference Attribute** (`ATTRIBUTE_NAME`)
+- The Page attribute that stores the image reference
+- **Constraints**:
+  - Must be a reference attribute
+  - Multiplicity: "At most one Value" (maximalOne)
+  - Content type: Document (File)
+  - Must be editable by the user
+
+### Display Configuration
+
+**Scaling** (`SCALING`)
+- Controls how the image fits within the widget area
+- Options:
+  - `horizontal`: Image scales to fill width (maintains aspect ratio)
+  - `vertical`: Image scales to fill height (maintains aspect ratio)
+  - `fit`: Image scales to fit within bounds (shows entire image)
+
+**Fixed Height** (`FIXED_HEIGHT`)
+- Optional maximum height in pixels
+- Constrains the image display area
+- When set, images won't exceed this height
+
+**Show Frame** (`SHOW_FRAME`)
+- Boolean toggle for displaying the widget frame
+- Default: `true`
+- When `false`, removes the standard widget border/frame
+
+**Localized Title** (`LOCALIZED_TITLE`)
+- Multi-language widget title
+- Displayed in the widget header (if frame is shown)
+
+## 5. User Interaction Flow
+
+### When No Image Is Set
+
+1. Widget displays an **upload button** with file picker
+2. Below that, a **table of available images** (existing Document children of the Page)
+3. User can:
+   - Click "Upload image" to browse and upload a new file
+   - Drag and drop a file onto the widget area
+   - Click "Insert this Image" button next to an available image
+
+### During Upload
+
+1. Progress bar appears showing upload percentage
+2. When complete, the image displays automatically
+3. The attribute reference is updated to point to the new Document
+
+### When Image Is Set
+
+1. Image displays with configured scaling
+2. **Remove button** (red X) appears in top-right corner
+3. Clicking the image opens it in a lightbox view
+4. Clicking remove:
+   - Clears the attribute reference
+   - Returns to the "no image" state
+   - Shows available images for selection
+
+### Permission Handling
+
+- If user lacks **read permissions** on the referenced Document: Shows "insufficient rights" message
+- If user lacks **edit permissions** on the attribute: Upload/remove buttons hidden
+- If user lacks **create document permissions** on the Page: Upload disabled
+
+## 6. Related Context
+
+### Widget Family
+
+This is the base widget in a family of three image display widgets:
+
+1. **cf.cplace.dragAndDropImageView.widget** (Image)
+   - Basic image display with upload
+
+2. **cf.cplace.imageWithText.widget** (Image with text)
+   - Extends base widget
+   - Adds overlay text with configurable positioning
+   - Text supports rich formatting (HTML)
+
+3. **cf.cplace.imageWithTextAndList.widget** (Image with text and list)
+   - Extends image with text
+   - Adds a search/list component below the image
+   - Useful for showing related entities with a visual header
+
+### Dependencies
+
+- **cplace Platform**: Core platform functionality
+- **Page Architecture**: Widget must be embedded in a Page entity
+- **Document Management**: Relies on Document entity type and file handling
+- **Permission System**: Respects read/edit permissions on attributes and entities
+
+### Technical Prerequisites
+
+- Page must have a reference attribute configured with:
+  - Type: Reference to Document
+  - Multiplicity: At most one value
+- User must have appropriate permissions on:
+  - The Page (to edit)
+  - The attribute (to edit)
+  - Document creation (to upload)
+
+## 7. Implementation Details
+
+### Frontend (TypeScript/AngularJS)
+
+**Controller**: `DragAndDropImageViewCtrl`
+- Manages widget state (image source, available images, permissions)
+- Handles remove/insert operations via HTTP POST
+- Manages upload progress display
+
+**Directive**: `cfCplaceDragAndDropImageView`
+- Angular directive for DOM integration
+- Initializes controller with serialized state from backend
+
+**State Model**: `IDragAndDropImageViewState`
+```typescript
+{
+  insertUrl: string;        // Endpoint for inserting existing image
+  removeUrl: string;        // Endpoint for removing current image
+  uploadUrl: string;        // Endpoint for uploading new image
+  scaling: 'horizontal' | 'vertical' | 'fit';
+  maxHeight: number;
+  insufficientRights: boolean;
+  imageSrc: string;         // Current image URL
+  availableImages: IImageDocument[];  // Selectable images
+}
+```
+
+### Backend (Java)
+
+**Widget Definition**: `DragAndDropImageViewWidgetDefinition`
+- Defines widget metadata and configuration schema
+- Builds widget state JSON for frontend
+- Validates embedding (must be in a Page)
+
+**Handlers**:
+- `UploadHandler`: Validates file, creates Document, updates reference
+- `InsertHandler`: Links existing Document to attribute
+- `RemoveHandler`: Clears reference, returns updated available images list
+- `AbstractDragAndDropImageHandler`: Common access checks and reference updates
+
+**Configuration Type**: `DRAG_AND_DROP_IMAGE_WIDGET.TYPE`
+- TypeDef defining configuration attributes
+- Enforces attribute constraints via `DocumentReferenceAttributeEnumerationProvider`
+
+### Styling
+
+The widget includes CSS classes for:
+- Image scaling modes (`.horizontal`, `.vertical`, `.fit`)
+- Remove button positioning and hover effects
+- Progress bar styling for uploads
+- Table layout for available images
+- Responsive image display
+
+## 8. Key Design Decisions
+
+### Why Store as Attribute Reference?
+
+Storing the image as an attribute reference (rather than just a child Document) allows:
+- **Querying**: Search for Pages by their image attribute
+- **Validation**: Enforce that exactly one image is set
+- **Workflows**: Trigger automations when the image changes
+- **Data Model**: Image becomes part of the Page's structured data
+
+### Why Show Available Images?
+
+The widget lists all image Documents on the Page to:
+- Enable **reuse** of uploaded images
+- Provide **visual selection** without browsing file system
+- Show **metadata** (name, size, modification date)
+- Reduce **duplicate uploads**
+
+### Scaling Options Rationale
+
+Three scaling modes support different use cases:
+- **Horizontal**: Wide images that should fill width (banners, headers)
+- **Vertical**: Tall images that should fill height (portraits, posters)
+- **Fit**: Ensure entire image is visible without cropping
+
+## 9. Limitations and Constraints
+
+### Attribute Requirements
+- **Must** be a reference attribute to Document type
+- **Must** have "At most one value" multiplicity
+- Cannot be used with multi-value attributes
+
+### Entity Type Constraint
+- Only embeddable in **Page** entities
+- Cannot be used on other entity types
+
+### Single Image Only
+- Widget manages exactly one image reference
+- For multiple images, multiple widgets or gallery solutions needed
+
+### File Type
+- Relies on Document validation and allowed extensions
+- Respects platform-wide file upload restrictions
+
+## 10. Search Keywords
+
+For finding this widget in codebase or documentation:
+
+- Image upload widget
+- Drag and drop image
+- Page image display
+- Document reference widget
+- Image attribute widget
+- File upload widget
+- Image viewer widget
+- cplace image widget
+- cf.cplace.dragAndDropImageView

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

@@ -0,0 +1,210 @@
+# Widget Research: cf.cplace.draggablePageList.widget
+
+## Widget Overview
+
+**Widget ID:** `cf.cplace.draggablePageList.widget`
+**Widget Name:** Drag and Drop Prioritization
+**App:** Drag and Drop List (cf.cplace.draggablePageList)
+**Repository:** cplace-paw
+**Version:** 25.3.5
+**Definition Class:** `cf.cplace.draggablePageList/src/main/java/cf/cplace/draggablePageList/script/DraggablePageListWidgetDefinition.java`
+
+## Purpose
+
+**1-2 Sentence Description:**
+
+The Drag and Drop Prioritization widget displays pages from a search query in a sortable list where users can change the order or priority of items through drag-and-drop interactions. It enables visual prioritization and sorting of pages by storing the order in a configurable numeric attribute, with support for separating sorted and unsorted entries.
+
+## Use Cases
+
+### Primary Use Cases
+
+1. **Task Prioritization**
+   - Managing task backlogs where items need to be ordered by priority
+   - Sprint planning with drag-and-drop story prioritization
+   - Work item ranking and ordering
+
+2. **Visual Roadmap Management**
+   - Ordering features or initiatives by priority
+   - Timeline sequencing of deliverables
+   - Release planning with priority-based sorting
+
+3. **Process Management**
+   - Workflow step ordering
+   - Queue management for items awaiting processing
+   - Sequential process planning
+
+4. **Resource Allocation**
+   - Prioritizing resource requests or assignments
+   - Budget allocation ordering
+   - Service request queue management
+
+### When to Choose This Widget
+
+Users should choose this widget when:
+- They need to visually manage the priority or order of a set of pages
+- The order/priority needs to be persisted in a numeric attribute
+- They want an intuitive drag-and-drop interface for reordering
+- They need to separate sorted items from unsorted/new items
+- They want to display responsible users and additional metadata alongside items
+
+### Problem It Solves
+
+The widget solves the problem of managing item priorities without manually entering numeric values. Instead of:
+- Opening each page individually to set a priority number
+- Calculating numeric gaps for inserting items between others
+- Maintaining complex ordering logic
+
+Users can simply drag and drop items into the desired order, and the widget automatically handles the numeric attribute updates.
+
+## Core Functionality
+
+### Main Features
+
+1. **Drag-and-Drop Sorting**
+   - Visual reordering of items through drag-and-drop
+   - Automatic persistence of order to a configurable numeric attribute
+   - Maintains sorted order based on the order attribute
+
+2. **Dual List Display**
+   - Primary list for sorted entries
+   - Optional secondary list for unsorted entries (items without a defined order value)
+   - Can display unsorted entries vertically (below) or horizontally (side-by-side)
+
+3. **Rich Item Display**
+   - Item title with clickable link
+   - Optional type indicator icons
+   - Responsible user avatars with overflow handling
+   - Label indicators from configurable attributes
+   - Additional icon attributes for visual metadata
+   - Blocked item highlighting
+
+4. **Hit Count Protection**
+   - Configurable maximum item limit (default: 1000)
+   - Error display when search results exceed the limit
+   - Prevents performance issues with large datasets
+
+## Configuration Concepts
+
+### Essential Configuration Options
+
+1. **Search Configuration**
+   - Defines which pages should be displayed in the widget
+   - Must result in pages of a single type
+   - Subject to hit count limit validation
+
+2. **Order Attribute** (`orderAttribute`)
+   - Sortable numeric attribute that stores the item's position
+   - Required for maintaining sort order
+   - Automatically updated when items are dragged and dropped
+
+3. **Display Options**
+   - **Height** (`height`): Widget height in pixels for layout control
+   - **Title** (`title_name`): Widget title/header text
+   - **Show Unsorted Entries** (`showUnsortedEntries`): Toggle display of items without order values
+   - **Show Unsorted Entries Horizontally** (`showUnsortedEntriesHorizontallly`): Layout mode for unsorted items
+
+4. **Item Metadata**
+   - **Type Icon Attribute** (`typeIconAttribute`): Attribute containing type indicator icons
+   - **Responsible User Attribute** (`responsibleUserAttribute`): User reference attribute for showing responsible parties
+   - **Label Indicator Attributes** (`labelIndicatorAttributes`): Attributes whose values display as labels/tags
+   - **Additional Icon Attributes** (`additionalIconAttributes_name`): Additional attributes for icon display
+   - **Blocked Attribute** (`blockedAttribute`): Boolean/indicator attribute to highlight blocked items
+
+5. **Performance**
+   - **Hit Count Limit** (`hitCountLimit`): Maximum number of items to display (default: 1000)
+
+### Different Modes/Variants
+
+1. **Single List Mode**
+   - Only displays sorted entries
+   - Used when all items have an order value
+   - `showUnsortedEntries` = false
+
+2. **Vertical Dual List Mode**
+   - Sorted entries shown first
+   - Unsorted entries displayed below sorted ones
+   - `showUnsortedEntries` = true, `showUnsortedEntriesHorizontallly` = false
+
+3. **Horizontal Dual List Mode**
+   - Sorted and unsorted entries shown side-by-side
+   - Useful for "backlog" vs "prioritized" visualization
+   - `showUnsortedEntries` = true, `showUnsortedEntriesHorizontallly` = true
+
+## Context and Relationships
+
+### Related Widgets
+
+- **cf.platform.embeddedSearchAsList**: Standard search results list without drag-and-drop capability
+- **cf.cplace.dragAndDropImageView.imageWithTextAndListWidget**: Another drag-and-drop widget for different visualization
+- **cf.cplace.landingPageFromPage.simpleListWithAttachment**: List widget with attachment support
+- **de.visualistik.visualRoadmap.widget**: Roadmap visualization that may use similar prioritization concepts
+
+### Prerequisites
+
+1. **Data Model Requirements**
+   - Target page type must have a numeric attribute for storing order/priority
+   - Optional: user reference attribute for responsible users
+   - Optional: attributes for icons, labels, and blocked status
+
+2. **Search Configuration**
+   - Must configure a search that returns pages of a single type
+   - Search results must be within the hit count limit
+
+3. **Permissions**
+   - Users need edit permissions on the order attribute to reorder items
+   - Users need read permissions to view the listed pages
+
+### Part of Larger Feature Set
+
+The widget is part of the **Drag and Drop List App** (cf.cplace.draggablePageList), which provides:
+- App Display Name: "Drag and Drop List"
+- App Icon: FontAwesome "fa-arrows"
+- App Description: "The Drag and Drop List displays pages in a sortable list. Sorting or prioritization can be changed by drag and drop."
+
+This app is focused on providing visual, interactive prioritization and ordering capabilities within the cplace platform.
+
+### Integration Points
+
+1. **Search System**
+   - Relies on cplace's search functionality to retrieve pages
+   - Validates that search returns a single page type
+   - Handles attribute migration when types/attributes change
+
+2. **Attribute System**
+   - Reads from configurable display attributes (icons, labels, users)
+   - Writes to the order attribute when items are reordered
+   - Supports attribute migration for widget configuration updates
+
+3. **Widget Framework**
+   - Extends cplace's standard WidgetDefinition class
+   - Supports fixed height configuration
+   - Implements widget configuration migration
+
+## Technical Notes
+
+### Implementation Details
+
+- **Framework**: Uses AngularJS for frontend interactivity
+- **Template**: HTML template with conditional sections for sorted/unsorted display
+- **Icon**: FontAwesome "fa-arrows" representing drag-and-drop capability
+- **Error Handling**:
+  - Displays warning if ordering operation fails
+  - Shows error alert when hit count limit is exceeded
+  - Validates search returns single type during migration
+
+### Behavioral Characteristics
+
+1. **Ordering Persistence**: Changes made via drag-and-drop immediately persist to the database
+2. **Sorted vs Unsorted**: Items are automatically categorized based on whether they have a value in the order attribute
+3. **User Display**: Shows up to a limited number of responsible user avatars with "+N" overflow indicator
+4. **Blocked Items**: Visual styling to indicate blocked/disabled items that may not be actionable
+
+## Research Sources
+
+- Widget Definition Class: `DraggablePageListWidgetDefinition.java` (decompiled from JAR)
+- App Definition Class: `DraggablePageListApp.java` (decompiled from JAR)
+- Widget Template: `draggablePageListWidgetDefinition.htm`
+- Internationalization: `messages_en.properties`, `messages_de.properties`
+- Plugin Descriptor: `pluginDescriptor.json`
+- Widget extracted from: `cf.cplace.draggablePageList-25.3.5.jar`