@cplace/test-mcp-server 0.1.15 → 1.1.0

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

@@ -0,0 +1,295 @@
+# Tuples Widget Research
+
+## Widget Information
+
+- **Widget ID**: `cf.cplace.tuplesWidget.widget`
+- **Widget Name**: Tuple
+- **Repository**: `cplace-paw`
+- **Definition Class**: `cf.cplace.tuplesWidget/src/main/java/cf/cplace/tuplesWidget/script/TuplesWidgetDefinition.java`
+
+## Purpose
+
+### What This Widget Does
+
+The Tuples Widget displays and manages referenced entities (called "tuples") in a structured table format. It provides an interactive interface for viewing, editing, creating, deleting, and reordering entities that are referenced through a multi-reference attribute on a page.
+
+**One-sentence description**: The Tuples Widget displays referenced entities in a table format with inline editing capabilities and CRUD operations.
+
+**Extended description**: The Tuples Widget provides a specialized table view for managing collections of referenced pages (tuples) through a multi-reference attribute, offering configurable columns, inline editing, drag-and-drop reordering, and integrated create/delete functionality.
+
+## Core Concepts
+
+### What are "Tuples" in cplace?
+
+In the context of this widget, "tuples" refer to **referenced entities** (pages) that are linked to the current page through a reference attribute. The term "tuple" is used to describe:
+
+- Pages of a specific type that are referenced from the current page
+- Entities that form a collection or list relationship
+- Related records that need to be displayed and managed as a group
+
+The widget specifically works with:
+- **Reference attributes** with multi-value multiplicity (0..* or similar)
+- **Target type definitions** that define what kind of pages can be referenced
+- **Attribute definitions** from the referenced type that should be displayed as columns
+
+### Key Terminology
+
+- **Tuple**: A referenced entity/page that is displayed in the widget
+- **Tuple Type**: The type definition of the referenced pages
+- **Tuple Attribute**: The reference attribute on the current page that holds the references to tuples
+- **Shown Tuple Attributes**: The attributes from the tuple type that should be displayed as columns in the table
+
+## Use Cases
+
+### When to Use This Widget
+
+1. **Master-Detail Relationships**
+   - Display a list of related detail records for a master record
+   - Example: A project page showing a list of related tasks, risks, or milestones
+   - Example: A customer page displaying a list of contacts or orders
+
+2. **Structured Data Collections**
+   - Manage collections of structured data entries
+   - Example: Configuration items, checklist entries, or requirements
+   - When you need to show multiple attributes of each referenced item in a table format
+
+3. **Editable Reference Lists**
+   - When users need to create, edit, and delete referenced items directly from the parent page
+   - Inline editing of tuple attributes without navigating away
+   - Quick creation of new related entities
+
+4. **Ordered Collections**
+   - When the order of referenced items matters
+   - Drag-and-drop reordering of tuple entries
+   - Maintaining a specific sequence of related items
+
+5. **Configurable Views of Related Data**
+   - When you need to show only specific attributes of referenced items
+   - Custom column selection from the available tuple attributes
+   - Showing a subset of information without the full page view
+
+### Problem This Widget Solves
+
+The widget solves the problem of managing **collections of related entities** without requiring users to:
+- Navigate to separate pages for each item
+- Use complex embedded search widgets
+- Manually maintain relationships between entities
+- Switch between view and edit modes
+
+It provides a **spreadsheet-like interface** for managing related data while maintaining the full cplace data model and permissions.
+
+## Configuration Concepts
+
+### Main Configuration Options
+
+#### 1. Reference Attribute Selection
+- **Configuration**: `ATTRIBUTE_NAME` (Tuple Attribute)
+- **Purpose**: Selects which reference attribute from the current page should be managed by the widget
+- **Requirements**: Must be a reference attribute that points to a single tuple type
+- **Behavior**: Determines what entities are displayed in the widget
+
+#### 2. Visible Columns
+- **Configuration**: `SHOWN_TUPLE_ATTRIBUTES_NAME` (Attributes of tuples to be shown in widget)
+- **Purpose**: Defines which attributes of the tuple type should appear as columns
+- **Options**:
+  - No selection = all attributes shown
+  - Select specific attributes = only those columns displayed
+- **Note**: Configuration must be saved after selecting tuple attribute to refresh available options
+
+#### 3. Tuple Name Column
+- **Configuration**: `SHOW_TUPLE_NAME_COLUMN` (Show name of tuple as column)
+- **Purpose**: Optionally display the tuple's name/title as a separate column
+- **Default**: `false` (not shown)
+
+#### 4. Sorting Options
+- **Configuration**: `SORT_BY_TUPLE_ATTRIBUTE_NAME` (Sort by) and `SORT_ORDER` (Sort Order)
+- **Purpose**: Define automatic sorting of tuple entries
+- **Options**: Ascending or Descending by any tuple attribute
+- **Restriction**: Cannot be used together with "Allow reordering" (manual ordering)
+
+#### 5. Widget Title
+- **Configuration**: `WIDGET_TITLE` (Widget title)
+- **Purpose**: Custom title for the widget
+- **Fallback**: If not set, uses the localized name of the reference attribute
+
+#### 6. Fixed Height
+- **Configuration**: `FIXED_HEIGHT` (Height of the widget in pixels)
+- **Purpose**: Set a fixed height for the widget with scrolling
+- **Default**: No fixed height (grows with content)
+
+### Permission Toggles
+
+The widget provides fine-grained control over what operations users can perform:
+
+#### 1. Allow Reordering
+- **Configuration**: `ALLOW_REORDERING_TUPLES`
+- **Default**: `true`
+- **Effect**: Shows up/down buttons or drag handles to reorder tuples
+- **Requirements**:
+  - User must have edit permission on the tuple attribute
+  - At least 2 tuples must exist
+  - Cannot be used with automatic sorting
+
+#### 2. Allow Adding
+- **Configuration**: `ALLOW_ADDING_TUPLES`
+- **Default**: `true`
+- **Effect**: Shows "Create [Type]" button to add new tuples
+- **Requirements**:
+  - User must have permission to create pages of the tuple type
+  - User must have edit permission on the tuple attribute
+  - Respects multiplicity constraints (e.g., max 1)
+
+#### 3. Allow Editing
+- **Configuration**: `ALLOW_EDITING_TUPLES`
+- **Default**: `true`
+- **Effect**: Makes tuple attributes editable inline (in-place editing)
+- **Requirements**: User must have edit permission on individual tuples
+
+#### 4. Allow Deleting
+- **Configuration**: `ALLOW_DELETING_TUPLES`
+- **Default**: `true`
+- **Effect**: Shows delete button for each tuple
+- **Requirements**:
+  - User must have delete permission on individual tuples
+  - Tuple must pass any custom deletion validation
+  - Extensions can prevent deletion (via `PreventRemoveTupleExtension`)
+
+### Modes and Variants
+
+The widget has **two mutually exclusive ordering modes**:
+
+1. **Manual Ordering Mode**
+   - Enabled when: `ALLOW_REORDERING_TUPLES = true` AND no sort attribute is set
+   - Behavior: Users can drag-and-drop or use buttons to reorder tuples
+   - Order is persisted in the reference attribute
+
+2. **Automatic Sorting Mode**
+   - Enabled when: A `SORT_BY_TUPLE_ATTRIBUTE_NAME` is configured
+   - Behavior: Tuples are automatically sorted by the specified attribute
+   - Users cannot manually change the order
+
+## Context and Dependencies
+
+### Related Widgets
+
+The Tuples Widget is part of a family of widgets for displaying related data:
+
+1. **Connected Attributes Group** (`cf.cplace.platform.connectedAttributesGroup`)
+   - Shows attributes of a single referenced entity
+   - Use when: You have a 1-to-1 relationship
+
+2. **Embedded Search Widgets** (`cf.platform.embeddedSearchAsTable`, `cf.platform.embeddedSearchAsList`)
+   - Show search results in table or list format
+   - Use when: You need complex filtering, aggregation, or cross-space searches
+
+3. **Table Widget** (`cf.cplace.platform.tableWidget`)
+   - Generic table for displaying data
+   - Use when: You need a simple read-only table
+
+4. **Table Detail View Widget** (`cf.cplace.tableDetailViewWidget.widget`)
+   - Shows table with expandable detail view
+   - Use when: You need a master-detail layout with more detail than fits in columns
+
+### Key Differences from Other Widgets
+
+**vs. Embedded Search Table**:
+- Tuples Widget: Direct reference management, inline editing, CRUD operations, manual ordering
+- Embedded Search: Read-only view, complex filtering, cross-space searches, aggregations
+
+**vs. Connected Attributes Group**:
+- Tuples Widget: Multiple referenced entities in table format
+- Connected Attributes: Single referenced entity with form layout
+
+**vs. Table Detail View**:
+- Tuples Widget: Simpler, focused on reference management
+- Table Detail View: More complex layout with expandable details
+
+### Prerequisites
+
+1. **Data Model Requirements**:
+   - A reference attribute must exist on the embedding page's type
+   - The reference attribute must point to a specific tuple type
+   - The tuple type should have attributes that make sense to display in columns
+
+2. **Permission Requirements**:
+   - Read access to the tuple type and its attributes
+   - Edit access to the reference attribute (for add/remove operations)
+   - Create/delete permissions on tuple type (for respective operations)
+
+3. **Embedding Context**:
+   - Must be embedded in a Page or TypeDefinition
+   - Cannot be embedded in other contexts (checked by `checkEmbeddableIn`)
+
+### Extension Points
+
+The widget provides several extension points for customization:
+
+1. **AssignReferenceToNewTupleExtension**
+   - Purpose: Add custom search filters when creating new tuples
+   - Use case: Restrict which tuples can be created based on business logic
+
+2. **TupleValidationErrorExtension**
+   - Purpose: Show custom error messages in the widget
+   - Use case: Display validation errors or warnings about the tuple collection
+
+3. **PreventRemoveTupleExtension**
+   - Purpose: Prevent deletion of specific tuples
+   - Use case: Protect required tuples or enforce business rules
+
+## Technical Implementation Notes
+
+### Widget Architecture
+
+1. **Backend Components**:
+   - `TuplesWidgetDefinition.java`: Widget definition and configuration
+   - `TuplesWidgetWidgetTypes.java`: Type definitions and attribute constraints
+   - `WidgetContent.java`: Main rendering logic, generates HTML content
+   - `TuplesWidgetConfInfo.java`: Configuration data transfer object
+
+2. **Handlers**:
+   - `ReloadHandler`: Refreshes widget content via AJAX
+   - `CreateReferenceHandler`: Handles creation of new tuple references
+   - `ChangedOrderHandler`: Persists new order after drag-and-drop
+   - `ConfirmDeleteHandler`: Shows delete confirmation dialog
+   - `SubmitDeleteHandler`: Performs actual deletion
+
+3. **Rendering**:
+   - Uses cplace's template system
+   - Generates HTML table with inline editing controls
+   - AJAX-based updates for dynamic operations
+   - No separate template file (generated programmatically)
+
+### Key Features
+
+1. **In-Place Editing**:
+   - Uses cplace's `show` function with inline editing flag
+   - Respects attribute-level permissions
+   - Can be disabled per widget instance
+
+2. **Dynamic Column Configuration**:
+   - Columns are determined by tuple type attributes
+   - Filterable by configuration
+   - Includes optional name column
+
+3. **Order Management**:
+   - Manual ordering via drag-and-drop or buttons
+   - Persisted in the reference attribute's order
+   - OR automatic sorting by any tuple attribute
+
+4. **CRUD Operations**:
+   - Create: Opens new page creation dialog with pre-filled reference
+   - Edit: Inline editing of visible attributes
+   - Delete: Confirmation dialog before deletion
+   - All operations respect permissions and validation
+
+## Summary
+
+The Tuples Widget is a versatile tool for managing collections of related entities in cplace. It provides a **table-based interface** that combines viewing, editing, and managing referenced pages without leaving the parent page. Its strength lies in:
+
+- **Inline editing capabilities** for quick data entry
+- **Flexible configuration** of visible columns and permissions
+- **Integrated CRUD operations** for referenced entities
+- **Manual or automatic ordering** options
+- **Permission-aware UI** that adapts to user rights
+
+Choose this widget when you need to manage a collection of structured, related data with a balance between simplicity and functionality.

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

@@ -0,0 +1,154 @@
+# Video Widget Research
+
+**Widget ID:** `cf.cplace.videoWidget`
+**Repository:** `cplace-utility-widgets`
+**Definition Class:** `cf.cplace.videoWidget/src/main/java/cf/cplace/videoWidget/script/VideoWidgetDefinition.java`
+
+## Purpose
+
+The Video Widget displays video files and images on cplace pages with customizable dimensions and optional frame styling. It provides a simple way to embed video content directly on pages, supporting both standard video formats (with HTML5 video player controls) and image files as fallback.
+
+## Core Functionality
+
+The widget:
+- Displays video files using HTML5 `<video>` element with browser-native controls
+- Can also display image files when an image is selected instead of a video
+- Automatically detects file type based on MIME type (distinguishes between video and image files)
+- Provides configurable height while maintaining responsive width (100%)
+- Shows appropriate messages when no video is selected or browser doesn't support video playback
+- Supports localization (English and German messages included)
+
+**Key Implementation Details:**
+- Widget kind: `cf.cplace.videoWidget`
+- Display name: "Video"
+- Template location: `cf/cplace/videoWidget/script/videoWidgetDefinition.htm` (VideoWidgetDefinition.java:52)
+- Frontend directive: `cfCplaceVideoWidgetDirective` (cfCplaceVideoWidgetDirective.ts:19)
+- MIME type detection determines whether to render as `<video>` or `<img>` tag (VideoWidgetDefinition.java:62-65)
+
+## Use Cases
+
+1. **Educational Content**: Display instructional or training videos directly on project pages or documentation pages
+2. **Presentations & Demos**: Embed product demos, feature walkthroughs, or presentation recordings
+3. **Documentation**: Add visual content (videos or images) to enhance written documentation
+4. **Media Galleries**: Create visual portfolios or media collections on pages
+5. **Team Communication**: Share recorded meetings, status updates, or announcements in video format
+6. **Marketing Materials**: Display promotional videos, case studies, or customer testimonials
+
+**When to use this widget:**
+- When you need to embed video or image content directly on a cplace page
+- When you want browser-native video controls (play, pause, volume, fullscreen)
+- When you need responsive video display that adapts to container width
+- When you want a simple, no-configuration-needed media display solution
+
+## Configuration Options
+
+The widget provides four main configuration attributes (defined in VideoWidgetWidgetTypes.java:19):
+
+1. **Widget Title** (`WIDGET_TITLE`)
+   - Type: Localized String (optional)
+   - Purpose: Custom title displayed in widget frame
+   - Default: None (uses default widget name "Video")
+   - Location: VideoWidgetWidgetTypes.java:24-28
+
+2. **Show Frame** (`SHOW_FRAME`)
+   - Type: Boolean
+   - Purpose: Controls whether widget displays with a visible frame/border
+   - Default: `false` (no frame)
+   - Location: VideoWidgetWidgetTypes.java:31-35
+
+3. **Video File** (`VIDEO`)
+   - Type: Document Reference (single)
+   - Purpose: Reference to the video or image file to display
+   - Required: No (shows "No video was selected" message if empty)
+   - Note: Accepts any file type; widget automatically detects if it's an image or video
+   - Location: VideoWidgetWidgetTypes.java:38-42
+
+4. **Widget Height** (`WIDGET_HEIGHT`)
+   - Type: Number
+   - Purpose: Fixed height in pixels for the widget
+   - Required: Yes (exactly one value required)
+   - Note: Width is always 100% of container; actual displayed height is height-5px to account for padding
+   - Location: VideoWidgetWidgetTypes.java:45-49
+
+### Configuration Behavior
+
+- **No Padding**: Widget uses full container space without internal padding (VideoWidgetDefinition.java:74-76)
+- **Frame Control**: Frame visibility can be toggled independently via `SHOW_FRAME` configuration (VideoWidgetDefinition.java:79-81)
+- **File Detection**: Automatically determines render mode based on MIME type:
+  - Files starting with `image/` MIME type → rendered as `<img>` tag
+  - Other files → rendered as `<video>` tag with controls
+  - Location: VideoWidgetDefinition.java:62-65
+- **Responsive Width**: Always uses 100% width regardless of height setting (videoWidgetDefinition.htm:3,9)
+
+## Technical Context
+
+### Repository Context
+This widget is part of the **cplace-utility-widgets** repository, which contains general-purpose display widgets:
+- `cf.cplace.videoWidget` - Video/image display (this widget)
+- `cf.cplace.qrCodeWidget` - QR code generation
+- `cf.cplace.dynamicCodeBlockWidget` - Code block display
+- `cf.cplace.treeTableWidget` - Tree table display
+- `cf.cplace.extendedTreeTableWidget` - Enhanced tree table
+
+### Dependencies
+- Core dependency: `cf.cplace.platform` version 25.3.80
+- No external media player libraries required (uses native HTML5 video)
+- Built with TypeScript for frontend (AngularJS directive)
+
+### Widget Embedding
+- Can be embedded on any page as a widget
+- Embedding check performed via `checkEmbeddableIn()` (VideoWidgetDefinition.java:117-119)
+- Must be embedded as a widget (not inline in other contexts)
+
+### Browser Support
+- Requires HTML5 video support in browser
+- Displays fallback message: "Your browser does not support the video tag" for unsupported browsers (VideoWidgetDefinition.java:37-38)
+
+## Related Features
+
+### Widget State Management
+The widget uses a simple state object (VideoWidgetDefinition.java:121-128):
+```java
+private static class WidgetState {
+    String videoUrl;      // Absolute URL to video/image file
+    double videoHeight;   // Configured height in pixels
+    boolean isImage;      // True if file is an image, false for video
+}
+```
+
+This state is serialized to JSON and passed to the frontend directive for rendering.
+
+### Localization Support
+- English (`messages_en.properties`) and German (`messages_de.properties`) included
+- Messages for:
+  - Widget configuration labels (title, height, file, frame)
+  - User-facing messages (no video selected, browser not supported)
+  - Widget name in widget selector
+
+### Test Setup
+Example test configuration (VideoTestSetupHandler.java:54-59):
+- Video file: "Big Buck Bunny" (mov_bbb.mp4)
+- Height: 600 pixels
+- Title: "Big Buck Bunny"
+- Demonstrates typical usage pattern for embedding video content
+
+## Design Considerations
+
+### Why This Widget Exists
+- Provides simple video/image embedding without requiring external services (YouTube, Vimeo, etc.)
+- Leverages native HTML5 capabilities for better performance and privacy
+- Supports offline scenarios where external video hosting isn't available
+- Maintains consistent styling with cplace's widget framework
+
+### Limitations
+- No advanced video player features (chapters, subtitles, playback speed controls)
+- Relies on browser's native video codec support
+- File must be uploaded to cplace (no direct URL embedding to external sources)
+- Width always responsive (cannot set fixed width)
+
+### Alternatives
+When this widget might NOT be the best choice:
+- For YouTube/Vimeo videos → Consider using an iframe widget or embed widget
+- For complex video interactions → May need custom development
+- For streaming large video files → Consider external hosting platforms
+- For live video → Requires different streaming solution

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

@@ -0,0 +1,249 @@
+# Widget Research: cf.cplace.visualizations.scriptingHighcharts
+
+## 1. Widget Purpose
+
+### Short Description
+The **cplaceJS based Highcharts Visualization** widget enables users to create custom, interactive charts using the Highcharts JavaScript library through cplaceJS scripting, providing full access to Highcharts API capabilities for data visualization.
+
+### Detailed Purpose
+This widget allows developers and power users to:
+- Create highly customizable, interactive charts using JavaScript/cplaceJS
+- Leverage the full power of the Highcharts API for professional data visualizations
+- Build dynamic visualizations that respond to page data and user interactions
+- Display complex data patterns and relationships through various chart types (line, bar, pie, scatter, etc.)
+
+The widget executes custom cplaceJS code to generate Highcharts configuration objects, which are then rendered as interactive visualizations in the cplace platform.
+
+## 2. Use Cases
+
+### Primary Use Cases
+
+1. **Custom Data Dashboards**
+   - Create executive dashboards with custom KPI visualizations
+   - Build project status overview charts
+   - Display business metrics in tailored chart formats
+
+2. **Dynamic Data Visualization**
+   - Visualize search results in custom chart formats
+   - Display aggregated data from multiple pages
+   - Create interactive charts that update based on table selections
+
+3. **Advanced Analytics Displays**
+   - Build complex multi-series charts
+   - Create custom trend analyses
+   - Display comparative data across multiple dimensions
+
+4. **Connected Widget Scenarios**
+   - Visualize data from connected table widgets
+   - Update charts based on table row selections
+   - Create master-detail visualization patterns
+
+### When to Choose This Widget
+
+Choose this widget when:
+- Standard visualization widgets don't meet your requirements
+- You need specific Highcharts chart types or configurations
+- You require custom data processing before visualization
+- You need to combine data from multiple sources
+- You want full control over chart appearance and behavior
+
+## 3. Key Concepts & Configuration
+
+### Core Configuration Elements
+
+#### 1. **Data Source**
+The widget supports multiple data source types:
+- **Search**: Execute a search query and use results as `pages` in the script
+- **Connected Table**: Pull data from a connected table widget
+- **Selection**: Manually select specific pages to visualize
+- **Connected Table with Selection Only**: Only visualize selected rows from a connected table
+
+Configuration attributes:
+- `DATA_SOURCE` (AttributeGrouping): Main data source configuration
+- `SEARCH`: Optional search configuration
+- `CONNECTED_TABLE`: Reference to a connected table widget ID
+- `CONNECTED_TABLE_SELECTION_ONLY`: Boolean flag to use only selected rows
+- `SELECTION`: Manual page selection
+
+#### 2. **cplaceJS Script**
+The heart of the widget - custom JavaScript code that:
+- Processes input data (pages from search/selection)
+- Generates Highcharts configuration object
+- Returns the configuration for rendering
+
+Script attribute:
+- `SCRIPT`: The cplaceJS code that generates the chart configuration
+
+#### 3. **Display Options**
+- `LOCALIZED_TITLE`: Widget title (localized string)
+- `SHOW_FRAME`: Boolean to show/hide widget frame (default: true)
+- `HEIGHT`: Fixed height for the widget
+
+### Available Script Bindings
+
+When writing cplaceJS code, the following objects are available:
+
+1. **`embeddingPage`** (WrappedPage)
+   - The page where the widget is embedded
+   - Provides access to embedding page attributes and context
+
+2. **`messages`** (MessageProvider)
+   - Helper object for accessing localized messages
+   - Based on the type definition of the embedding page
+
+3. **`pages`** (Iterable<WrappedPage>)
+   - Collection of pages from the configured data source
+   - Results from search, selection, or connected table
+   - Lazy-loaded iterable for performance
+
+### Script Structure
+
+A typical cplaceJS script follows this pattern:
+
+```javascript
+// 1. Process data from pages
+var data = [];
+for (let page of pages) {
+    // Extract and process data
+    data.push({
+        x: page.get('someAttribute'),
+        y: page.get('anotherAttribute')
+    });
+}
+
+// 2. Build Highcharts configuration object
+var config = {
+    title: {
+        text: 'My Custom Chart'
+    },
+    chart: {
+        type: 'line',  // or 'bar', 'pie', 'scatter', etc.
+        spacingBottom: 25,
+        spacingTop: 20
+    },
+    tooltip: {
+        pointFormat: 'Value: {point.y}'
+    },
+    plotOptions: {
+        // Chart-type specific options
+    },
+    series: [{
+        name: 'Data Series',
+        data: data
+    }]
+};
+
+// 3. Return the configuration (last line)
+config
+```
+
+### Integration Features
+
+#### Connected Widget Support
+The widget implements:
+- **ISearchProducer**: Responds to search changes from connected widgets
+- **IMultiEntitySelectionProducer**: Responds to entity selection changes
+
+This enables:
+- Automatic chart refresh when connected table data changes
+- Dynamic filtering based on user selections
+- Cascading visualization updates
+
+#### Event Handling
+The widget responds to:
+- `TABLE_REFRESH`: Updates when connected table refreshes
+- `TABLE_DATA_CHANGED`: Updates when table data changes
+- `ROW_SELECTION_CHANGED`: Updates when table selection changes (if selection-only mode)
+- `SELECTED_SINGLE`: Handles single entity selection from nested connected tables
+
+### Error Handling & Debugging
+
+The widget provides:
+- **Error Display**: Shows script execution errors in the widget
+- **Log Output**: Displays console.log output from the script with a "Remove log" button
+- **Script Exception Handling**: Catches and displays both ScriptException and TypeConversionException
+
+## 4. Context & Relationships
+
+### Dependencies
+- **Parent Plugin**: `cf.cplace.visualizations` (provides base visualization functionality)
+- **Platform**: `cf.cplace.platform` (core platform capabilities)
+- **Highcharts Library**: JavaScript charting library (provided by platform)
+
+### Related Widgets
+- **cf.cplace.visualizations.scriptingLineChart**: Specialized version for line charts with simpler configuration
+- **Standard Visualization Widgets**: Non-scriptable alternatives in the visualizations plugin
+
+### Plugin Information
+- **Plugin**: `cf.cplace.scriptingVisualizations`
+- **Repository**: `cplace-paw`
+- **Widget Kind**: `cf.cplace.visualizations.scriptingHighcharts`
+
+### Technical Architecture
+
+#### Backend (Java)
+- **ScriptingHighchartsWidgetDefinition**: Widget definition and configuration handling
+- **ScriptingHighchartsWidgetHandler**: HTTP handler for loading chart data
+- **SaferScriptEngine**: Secure script execution environment
+
+Key execution flow:
+1. Widget configuration is loaded and validated
+2. Data source is resolved (search/selection/connected table)
+3. cplaceJS script is executed with bindings (embeddingPage, messages, pages)
+4. Script returns Highcharts configuration object
+5. Configuration is converted from JavaScript to JSON
+6. Result is sent to frontend with any errors/logs
+
+#### Frontend (TypeScript/AngularJS)
+- **ScriptingHighchartsWidgetCtrl**: Widget controller extending AbstractHighchartsWidgetCtrl
+- **scriptingHighchartsDirective**: AngularJS directive for widget rendering
+- **Event subscriptions**: Handles connected widget events and table updates
+
+Rendering flow:
+1. Widget loads and registers event listeners
+2. Makes HTTP POST to load chart configuration
+3. Receives configuration with potential errors/logs
+4. Initializes Highcharts with the configuration
+5. Displays chart or error message
+
+### Performance Considerations
+- Scripts are executed in a pooled engine environment for performance
+- Monitoring is enabled with thresholds for performance logging
+- Lazy iteration of pages prevents loading all data upfront
+- Chart data is loaded asynchronously via HTTP
+
+## 5. Migration & Compatibility
+
+### Deprecated Attributes
+- `TITLE` (SingleStringAttributeDef): Deprecated in favor of `LOCALIZED_TITLE`
+- Migration is handled automatically via `migrateWidgetConfiguration()`
+
+### Version Information
+- Current version: 25.3.5
+- Release: 25.3
+- Repository: cplace-paw
+
+## 6. Developer Notes
+
+### Security
+- Scripts run in a `SaferScriptEngine` with restricted capabilities
+- Allowed type classes: `Search.class`, `Filters.class`
+- Log output is collected through `LogCollector` (deprecated but still used internally)
+
+### Customization Points
+1. **Chart Types**: Any Highcharts chart type is supported
+2. **Data Processing**: Full JavaScript capabilities for data transformation
+3. **Styling**: Complete control over chart appearance via Highcharts options
+4. **Interactivity**: Can leverage Highcharts event handlers and interactions
+
+### Best Practices
+1. Keep scripts focused and performant
+2. Use console.log for debugging during development
+3. Test with actual data sources to validate data processing
+4. Consider selection-only mode for large tables to improve performance
+5. Return configuration objects that follow Highcharts API specifications
+
+### Known Limitations
+- Script execution is synchronous and can impact page load times if complex
+- No access to external libraries beyond what's available in the script engine
+- Error messages may be technical and require JavaScript knowledge to debug